Debian Codegraph @

cmake/tribits/ctest_driver/TribitsCTestDriverCore.cmake

raw
1 # @HEADER
2 # *****************************************************************************
3 # TriBITS: Tribal Build, Integrate, and Test System
4 #
5 # Copyright 2013-2016 NTESS and the TriBITS contributors.
6 # SPDX-License-Identifier: BSD-3-Clause
7 # *****************************************************************************
8 # @HEADER
9
10 #############################################
11 #
12 # TriBITS platform-independent test driver.
13 #
14 #############################################
15
16 message("")
17 message("*******************************")
18 message("*** TribitsCTestDriverCore ***")
19 message("*******************************")
20 message("")
21
22
23 cmake_minimum_required(VERSION 3.23.0 FATAL_ERROR)
24
25 set(THIS_CMAKE_CURRENT_LIST_DIR "${CMAKE_CURRENT_LIST_DIR}")
26
27 #
28 # Get the basic variables that define the project and the build
29 #
30
31 #
32 # Set TRIBITS_PROJECT_ROOT
33 #
34 # We must locate the source code root directory before processing this
35 # file. Once the root directory is located, we can make good guesses at other
36 # properties, but this file contains code that is executed in a CTest -S
37 # script that is always executed outside of the context of the project's CMake
38 # build.
39 #
40 # We allow the environment variable TRIBITS_PROJECT_ROOT to locate the
41 # root directory. If the variable doesn't exist, we fall back on the
42 # default convention.
43 #message("TRIBITS_PROJECT_ROOT (before env) = '${TRIBITS_PROJECT_ROOT}'")
44 if (NOT TRIBITS_PROJECT_ROOT)
45 set(TRIBITS_PROJECT_ROOT "$ENV{TRIBITS_PROJECT_ROOT}")
46 endif()
47 #message("TRIBITS_PROJECT_ROOT (after env) = '${TRIBITS_PROJECT_ROOT}'")
48 if (NOT TRIBITS_PROJECT_ROOT)
49 # Fall back on the default convention, in which this file is located at:
50 # <root>/cmake/tribits/ctest.
51 get_filename_component(CMAKE_CURRENT_LIST_DIR ${CMAKE_CURRENT_LIST_FILE} PATH)
52 set(TRIBITS_PROJECT_ROOT "${CMAKE_CURRENT_LIST_DIR}/../../..")
53 endif()
54 get_filename_component(TRIBITS_PROJECT_ROOT "${TRIBITS_PROJECT_ROOT}" ABSOLUTE)
55 message("TRIBITS_PROJECT_ROOT = '${TRIBITS_PROJECT_ROOT}'")
56
57 #
58 # Read in PROJECT_NAME
59 #
60 # Assert that the ProjectName.cmake file exists.
61 set(TRIBITS_PROJECT_NAME_INCLUDE "${TRIBITS_PROJECT_ROOT}/ProjectName.cmake")
62 if(NOT EXISTS "${TRIBITS_PROJECT_NAME_INCLUDE}")
63 message(FATAL_ERROR
64 "Could not locate ProjectName.cmake.\n"
65 " TRIBITS_PROJECT_ROOT = ${TRIBITS_PROJECT_ROOT}\n"
66 " Set the TRIBITS_PROJECT_ROOT environment variable "
67 "to point at the source root.")
68 endif()
69 # Include the ProjectName.cmake file and get PROJECT_NAME
70 include(${TRIBITS_PROJECT_NAME_INCLUDE})
71 if(NOT PROJECT_NAME)
72 message(FATAL_ERROR
73 "The project name has not been set!"
74 " It should be set in ${TRIBITS_PROJECT_ROOT}/ProjectName.cmake.")
75 endif()
76 message("PROJECT_NAME = ${PROJECT_NAME}")
77
78 #
79 # Set ${PROJECT_NAME}_TRIBITS_DIR
80 #
81 if (NOT "$ENV{${PROJECT_NAME}_TRIBITS_DIR}" STREQUAL "")
82 set(${PROJECT_NAME}_TRIBITS_DIR "$ENV{${PROJECT_NAME}_TRIBITS_DIR}")
83 endif()
84 if ("${${PROJECT_NAME}_TRIBITS_DIR}" STREQUAL "")
85 set(${PROJECT_NAME}_TRIBITS_DIR "${TRIBITS_PROJECT_ROOT}/cmake/tribits")
86 endif()
87 message("${PROJECT_NAME}_TRIBITS_DIR = ${${PROJECT_NAME}_TRIBITS_DIR}")
88 # ToDo: If you are really going to allow setting a different
89 # ${PROJECT_NAME}_TRIBITS_DIR from where this module lives, then you need to
90 # split off the implementation of this module into a separate
91 # TribitsCTestDriverCoreImpl.cmake module and then include that based on the
92 # set ${PROJECT_NAME}_TRIBITS_DIR var.
93
94 #
95 # Set default for CTEST_SOURCE_DIRECTORY
96 #
97 if ("${CTEST_SOURCE_DIRECTORY}" STREQUAL "")
98 message("Set default for CTEST_SOURCE_DIRECTORY to TRIBITS_PROJECT_ROOT='TRIBITS_PROJECT_ROOT='${TRIBITS_PROJECT_ROOT}'")
99 set(CTEST_SOURCE_DIRECTORY ${TRIBITS_PROJECT_ROOT})
100 endif()
101
102 #
103 # Set default for CTEST_BINARY_DIRECTORY
104 #
105 if ("${CTEST_BINARY_DIRECTORY}" STREQUAL "")
106 message("Set default for CTEST_BINARY_DIRECTORY to $PWD/BUILD='$ENV{PWD}/BUILD'")
107 set(CTEST_BINARY_DIRECTORY $ENV{PWD}/BUILD)
108 endif()
109
110 include("${CMAKE_CURRENT_LIST_DIR}/../core/common/TribitsConstants.cmake")
111 tribits_asesrt_minimum_cmake_version()
112 include("${CMAKE_CURRENT_LIST_DIR}/../core/common/TribitsCMakePolicies.cmake" NO_POLICY_SCOPE)
113
114 #
115 # Set CMAKE_MODULE_PATH
116 #
117 set( CMAKE_MODULE_PATH
118 "${TRIBITS_PROJECT_ROOT}"
119 "${TRIBITS_PROJECT_ROOT}/cmake"
120 "${${PROJECT_NAME}_TRIBITS_DIR}/core/utils"
121 "${${PROJECT_NAME}_TRIBITS_DIR}/core/common"
122 "${${PROJECT_NAME}_TRIBITS_DIR}/core/test_support"
123 "${${PROJECT_NAME}_TRIBITS_DIR}/core/package_arch"
124 "${${PROJECT_NAME}_TRIBITS_DIR}/ci_support"
125 "${${PROJECT_NAME}_TRIBITS_DIR}/ctest_driver"
126 )
127
128 include(Split)
129 include(PrintVar)
130 include(MultilineSet)
131 include(SetDefaultAndFromEnv)
132 include(AssertDefined)
133 include(AppendSet)
134 include(AppendStringVar)
135 include(TribitsGlobalMacros)
136 include(TribitsStripCommentsFromCMakeCacheFile)
137
138 # Need to include the project's version file to get some Git and CDash
139 # settings specific to the given version
140 tribits_project_read_version_file(${TRIBITS_PROJECT_ROOT})
141
142 include(TribitsFindPythonInterp)
143 tribits_find_python()
144 message("Python3_EXECUTABLE = ${Python3_EXECUTABLE}")
145
146 #############################
147 ### Do some initial setup ###
148 #############################
149
150
151 # Get the host type
152
153 if(WIN32)
154 set(HOST_TYPE $ENV{OS})
155 else()
156 find_program(UNAME_EXE NAMES uname)
157 execute_process(
158 COMMAND ${UNAME_EXE}
159 OUTPUT_VARIABLE HOST_TYPE
160 OUTPUT_STRIP_TRAILING_WHITESPACE
161 )
162 endif()
163
164
165 # Find git
166
167 find_package(Git REQUIRED)
168
169
170 # Find gitdist
171
172 set(GITDIST_EXE "${${PROJECT_NAME}_TRIBITS_DIR}/python_utils/gitdist")
173
174
175 # Get the host name
176
177 site_name(CTEST_SITE_DEFAULT)
178
179
180 # Get helper functions
181
182 include(TribitsCTestDriverCoreHelpers)
183
184
185 # @FUNCTION: tribits_ctest_driver()
186 #
187 # Universal platform-independent CTest/CDash driver function for CTest -S
188 # scripts for TriBITS projects
189 #
190 # Usage (in ``<script>.cmake`` file run with ``CTest -S <script>.cmake``)::
191 #
192 # # Set some basic vars and include tribits_ctest_driver()
193 # set(TRIBITS_PROJECT_ROOT "${CMAKE_CURRENT_LIST_DIR}/../../../..")
194 # include(
195 # "${TRIBITS_PROJECT_ROOT}/cmake/tribits/ctest_driver/TribitsCTestDriverCore.cmake")
196 #
197 # # Set variables that define this build
198 # set(CTEST_BUILD_NAME <buildName>)
199 # set(CTEST_TEST_TYPE Nightly)
200 # set(CTEST_DASHBOARD_ROOT PWD)
201 # set(MPI_EXEC_MAX_NUMPROCS 16)
202 # set(CTEST_BUILD_FLAGS "-j16")
203 # set(CTEST_PARALLEL_LEVEL 16)
204 # set(${PROJECT_NAME}_REPOSITORY_LOCATION <git-url-to-the-base-git-repo>)
205 # [... Set other vars ...]
206 #
207 # # Call the driver script to handle the rest
208 # tribits_ctest_driver()
209 #
210 # This platform independent code is used in CTest -S scripts to drive the
211 # testing process for submitting to CDash for a TriBITS project.
212 #
213 # This function drives the following operations:
214 #
215 # 1) **Clone or update all source version control (VC) repos** (Only if
216 # `CTEST_DO_UPDATES`_ ``= TRUE``, otherwise existing source tree pointed to
217 # by `CTEST_SOURCE_DIRECTORY`_ must already be in place). Submit "Update"
218 # data to CDash.
219 #
220 # 2) **Empty the build directory** pointed to by `CTEST_BINARY_DIRECTORY`_
221 # (only if `CTEST_DO_NEW_START`_ ``= TRUE`` and
222 # `CTEST_START_WITH_EMPTY_BINARY_DIRECTORY`_ ``= TRUE``).
223 #
224 # 3) **Generate the file <Project>PackageDependencies.xml** which is needed to
225 # determine which packages need to be tested based on changes (only if
226 # `CTEST_GENERATE_OUTER_DEPS_XML_OUTPUT_FILE`_ ``= TRUE``).
227 #
228 # 4) **Generate the file CDashSubprojectDependencies.xml** (only if
229 # `CTEST_SUBMIT_CDASH_SUBPROJECTS_DEPS_FILE`_ ``= TRUE``). Submit file to
230 # CDash to inform of subproject structure and email addresses.
231 #
232 # 5) **Determine the set of packages to be tested**. If
233 # `CTEST_ENABLE_MODIFIED_PACKAGES_ONLY`_ ``= TRUE``, then this is
234 # determined by the files that have changed since the last build and
235 # therefore what TriBITS packages need to be tested (can only be used if
236 # and the underlying source tree repos must are git repos). Otherwise, one
237 # can directly set `${PROJECT_NAME}_PACKAGES`_ and other variables (see
238 # `Determining What Packages Get Tested (tribits_ctest_driver())`_).
239 #
240 # 6) **Start a new dashboard calling ctest_start()** which defines a new CDash
241 # build (with a unique Build Stamp) (only if `CTEST_DO_NEW_START`_ ``=
242 # TRUE``).
243 #
244 # 7) **Configure the selected packages to be tested** in the build directory
245 # pointed to by `CTEST_BINARY_DIRECTORY`_. Submit "Configure" and "Notes"
246 # data to CDash (only if `CTEST_DO_CONFIGURE`_ ``= TRUE``).
247 #
248 # 8) **Build configured packages and the enabled package tests**. Submit
249 # "Build" data to CDash (only if `CTEST_DO_BUILD`_ ``= TRUE``).
250 #
251 # 9) **Install the configured and build targets**. Submit
252 # "Build" install data to CDash (only if `CTEST_DO_INSTALL`_ ``= TRUE``).
253 #
254 # 10) **Run enabled tests for the configured packages** (only if
255 # `CTEST_DO_TEST`_ = ``TRUE``). (Also, this will generate coverage data if
256 # `CTEST_DO_COVERAGE_TESTING`_ ``= TRUE``). Submit "Test" data to CDash.
257 #
258 # 11) **Collect coverage results from tests already run** (only if
259 # `CTEST_DO_COVERAGE_TESTING`_ ``= TRUE``). Submit "Coverage" data to
260 # CDash.
261 #
262 # 12) **Run dynamic analysis testing on defined test suite** (e.g. run
263 # ``valgrind`` with each of the test commands (only if
264 # `CTEST_DO_MEMORY_TESTING`_ ``= TRUE``). Submit "MemCheck" data to CDash.
265 #
266 # After each of these steps, results are submitted to CDash if
267 # `CTEST_DO_SUBMIT`_ ``= TRUE`` and otherwise no data is submitted to any
268 # CDash site (which is good for local debugging of CTest -S driver scripts).
269 # For the package-by-package mode these steps 7-11 for configure, build, and
270 # running tests shown above are actually done in a loop package-by-package
271 # with submits for each package to be tested. For the all-at-once mode, these
272 # steps are done all at once for the selected packages to be tested and
273 # results are submitted to CDash all-at-once for all packages together (see
274 # `All-at-once versus package-by-package mode (tribits_ctest_driver())`_).
275 #
276 # For context for how this function is used, see:
277 #
278 # * `TriBITS CTest/CDash Driver`_
279 # * `How to submit testing results to a CDash site`_
280 #
281 # Also note that this function executes `Reduced Package Dependency
282 # Processing`_ so all of the files described in that process are read in while
283 # this function runs. This processing is needed to determine the TriBITS
284 # package dependency graph and to determine the set of packages to be enabled
285 # or disabled when determining the set of packages to be tested.
286 #
287 # *Sections:*
288 #
289 # * `List of all variables (tribits_ctest_driver())`_
290 # * `Setting variables (tribits_ctest_driver())`_
291 # * `Source and Binary Directory Locations (tribits_ctest_driver())`_
292 # * `Determining What Packages Get Tested (tribits_ctest_driver())`_
293 # * `Setting variables in the inner CMake configure (tribits_ctest_driver())`_
294 # * `Determining what testing-related actions are performed (tribits_ctest_driver())`_
295 # * `Determining how the results are displayed on CDash (tribits_ctest_driver())`_
296 # * `Specifying where the results go to CDash (tribits_ctest_driver())`_
297 # * `Links to results on CDash (tribits_ctest_driver())`_
298 # * `Determining what TriBITS repositories are included (tribits_ctest_driver())`_
299 # * `All-at-once versus package-by-package mode (tribits_ctest_driver())`_
300 # * `Multiple ctest -S invocations (tribits_ctest_driver())`_
301 # * `Repository Updates (tribits_ctest_driver())`_
302 # * `Other CTest Driver options (tribits_ctest_driver())`_
303 # * `Return value (tribits_ctest_driver())`_
304 #
305 # .. _List of all variables (tribits_ctest_driver()):
306 #
307 # The following is an alphabetical listing of all of the variables that impact
308 # the behavior of the function ``tribits_ctest_driver()`` with links to their
309 # more detailed documentation:
310 #
311 # * ``${PROJECT_NAME}_ADDITIONAL_PACKAGES`` (`Determining What Packages Get Tested (tribits_ctest_driver())`_)
312 # * ``${PROJECT_NAME}_BRANCH`` (`Repository Updates (tribits_ctest_driver())`_)
313 # * ``${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE`` (`All-at-once versus package-by-package mode (tribits_ctest_driver())`_)
314 # * ``${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES`` (`Determining What Packages Get Tested (tribits_ctest_driver())`_)
315 # * ``${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES`` (`Determining What Packages Get Tested (tribits_ctest_driver())`_)
316 # * ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE``
317 # * ``${PROJECT_NAME}_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE`` (`Determining what TriBITS repositories are included (tribits_ctest_driver())`_)
318 # * ``${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE`` (`Determining What Packages Get Tested (tribits_ctest_driver())`_)
319 # * ``${PROJECT_NAME}_EXCLUDE_PACKAGES`` (`Determining What Packages Get Tested (tribits_ctest_driver())`_)
320 # * ``${PROJECT_NAME}_EXTRAREPOS_BRANCH`` (`Repository Updates (tribits_ctest_driver())`_)
321 # * ``${PROJECT_NAME}_EXTRAREPOS_FILE`` (`Determining what TriBITS repositories are included (tribits_ctest_driver())`_)
322 # * ``${PROJECT_NAME}_EXTRA_REPOSITORIES`` (`Determining what TriBITS repositories are included (tribits_ctest_driver())`_)
323 # * ``${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES`` (`Setting variables in the inner CMake configure (tribits_ctest_driver())`_)
324 # * ``${PROJECT_NAME}_INNER_ENABLE_TESTS`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
325 # * ``${PROJECT_NAME}_PACKAGES`` (`Determining What Packages Get Tested (tribits_ctest_driver())`_)
326 # * ``${PROJECT_NAME}_PRE_REPOSITORIES`` (`Determining what TriBITS repositories are included (tribits_ctest_driver())`_)
327 # * ``${PROJECT_NAME}_REPOSITORY_BRANCH`` (`Repository Updates (tribits_ctest_driver())`_)
328 # * ``${PROJECT_NAME}_REPOSITORY_LOCATION`` (`Repository Updates (tribits_ctest_driver())`_)
329 # * ``${PROJECT_NAME}_SKIP_CTEST_ADD_TEST`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
330 # * ``${PROJECT_NAME}_TRACK`` (`Determining how the results are displayed on CDash (tribits_ctest_driver())`_)
331 # * ``${PROJECT_NAME}_TRIBITS_DIR`` (`Source and Binary Directory Locations (tribits_ctest_driver())`_)
332 # * ``${PROJECT_NAME}_VERBOSE_CONFIGURE`` (`Other CTest Driver options (tribits_ctest_driver())`_)
333 # * ``COMPILER_VERSION`` (`Determining how the results are displayed on CDash (tribits_ctest_driver())`_)
334 # * ``CTEST_BINARY_DIRECTORY`` (`Source and Binary Directory Locations (tribits_ctest_driver())`_)
335 # * ``CTEST_BUILD_FLAGS`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
336 # * ``CTEST_BUILD_NAME`` (`Determining how the results are displayed on CDash (tribits_ctest_driver())`_)
337 # * ``CTEST_CHANGE_ID`` (`Determining how the results are displayed on CDash (tribits_ctest_driver())`_)
338 # * ``CTEST_CMAKE_GENERATOR`` (`Other CTest Driver options (tribits_ctest_driver())`_)
339 # * ``CTEST_CONFIGURATION_UNIT_TESTING`` (`Other CTest Driver options (tribits_ctest_driver())`_)
340 # * ``CTEST_COVERAGE_COMMAND`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
341 # * ``CTEST_DASHBOARD_ROOT`` (`Source and Binary Directory Locations (tribits_ctest_driver())`_)
342 # * ``CTEST_DO_BUILD`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
343 # * ``CTEST_DO_CONFIGURE`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
344 # * ``CTEST_DO_COVERAGE_TESTING`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
345 # * ``CTEST_DO_INSTALL`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
346 # * ``CTEST_DO_MEMORY_TESTING`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
347 # * ``CTEST_DO_NEW_START`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
348 # * ``CTEST_DO_SUBMIT`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
349 # * ``CTEST_DO_TEST`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
350 # * ``CTEST_DO_UPDATES`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
351 # * ``CTEST_ENABLE_MODIFIED_PACKAGES_ONLY`` (`Determining What Packages Get Tested (tribits_ctest_driver())`_)
352 # * ``CTEST_EXPLICITLY_ENABLE_IMPLICITLY_ENABLED_PACKAGES`` (`Determining What Packages Get Tested (tribits_ctest_driver())`_)
353 # * ``CTEST_GENERATE_OUTER_DEPS_XML_OUTPUT_FILE`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
354 # * ``CTEST_MEMORYCHECK_COMMAND_OPTIONS`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
355 # * ``CTEST_MEMORYCHECK_COMMAND`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
356 # * ``CTEST_NOTES_FILES`` (`Determining how the results are displayed on CDash (tribits_ctest_driver())`_)
357 # * ``CTEST_PARALLEL_LEVEL`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
358 # * ``CTEST_SITE`` (`Determining how the results are displayed on CDash (tribits_ctest_driver())`_)
359 # * ``CTEST_SOURCE_DIRECTORY`` (`Source and Binary Directory Locations (tribits_ctest_driver())`_)
360 # * ``CTEST_SOURCE_NAME`` (`Source and Binary Directory Locations (tribits_ctest_driver())`_)
361 # * ``CTEST_START_WITH_EMPTY_BINARY_DIRECTORY`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
362 # * ``CTEST_SUBMIT_CDASH_SUBPROJECTS_DEPS_FILE`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
363 # * ``CTEST_TEST_TYPE`` (`Determining how the results are displayed on CDash (tribits_ctest_driver())`_)
364 # * ``CTEST_UPDATE_ARGS`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
365 # * ``CTEST_UPDATE_VERSION_ONLY`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
366 # * ``CTEST_WIPE_CACHE`` (`Determining what testing-related actions are performed (tribits_ctest_driver())`_)
367 # * ``EXTRA_CONFIGURE_OPTIONS`` (`Setting variables in the inner CMake configure (tribits_ctest_driver())`_)
368 # * ``EXTRA_SYSTEM_CONFIGURE_OPTIONS`` (`Setting variables in the inner CMake configure (tribits_ctest_driver())`_)
369 # * ``TRIBITS_2ND_CTEST_DROP_LOCATION`` (`Specifying where the results go to CDash (tribits_ctest_driver())`_)
370 # * ``TRIBITS_2ND_CTEST_DROP_SITE`` (`Specifying where the results go to CDash (tribits_ctest_driver())`_)
371 # * ``TRIBITS_PROJECT_ROOT`` (`Source and Binary Directory Locations (tribits_ctest_driver())`_)
372 #
373 # **List of all variables (tribits_ctest_driver()):**
374 #
375 # .. _Setting variables (tribits_ctest_driver()):
376 #
377 # **Setting variables (tribits_ctest_driver()):**
378 #
379 # Variables can be set to control the behavior of this function before the
380 # function is called. Some variables must be set in the CTest -S driver
381 # script before calling this function ``tribits_ctest_driver()``. Many
382 # variables have a default value that will work in most cases.
383 #
384 # In general, these variables fall into one of three different categories:
385 #
386 # * **Variables that must be set in the outer CTest -S driver script before
387 # the TribitsCTestDriverCore.cmake module is even included:** Many of these
388 # can also be overridden from an env var of the same name. There are very
389 # few of these variables and they are specifically called out below.
390 #
391 # * **Variables with no default value that must set in the outer CTest -S
392 # driver script after the TribitsCTestDriverCore.cmake module is included
393 # but before tribits_ctest_driver() is called:** There are very few of these
394 # variables and in some cases, they may be optional. These types of
395 # variables will be called out below.
396 #
397 # * **Variables that can be are set before tribits_ctest_driver() is called
398 # but have default values provided in the tribits_ctest_driver() function
399 # and may look for env var overrides:** This comprises the majority of the
400 # variables used in ``tribits_ctest_driver()``. The variables that have
401 # default values but allow for an override as an env var use the function
402 # `set_default_and_from_env()`_. In the case of variables that are given a
403 # default value with ``set_default_and_from_env()``, their value is always
404 # overridden with what is in the env var of the same name. In this case,
405 # the overriding value that is read in from the env is printed out. In
406 # either case, the value used for these variables is printed out.
407 #
408 # Which variables are which are described below for each variable.
409 #
410 # .. _Source and Binary Directory Locations (tribits_ctest_driver()):
411 #
412 # **Source and Binary Directory Locations (tribits_ctest_driver()):**
413 #
414 # To understand how to set the source and binary directories, one must
415 # understand that CTest -S scripts using this function get run in one of two
416 # different modes:
417 #
418 # **Mode 1**: Run where there are **already existing source and binary
419 # directories** (i.e. is set empty before call). In this case,
420 # `CTEST_SOURCE_DIRECTORY`_ and `CTEST_BINARY_DIRECTORY`_ must be set by the
421 # user before calling this function (and `CTEST_DASHBOARD_ROOT`_ is empty).
422 # This mode is typically used to test a local build or an existing cloned and
423 # setup set source tree and post to CDash (see the custom ``dashboard`` target
424 # in `Dashboard Submissions`_).
425 #
426 # **Mode 2**: A **new binary directory is created and optionally new sources
427 # are cloned or updated** under a driver directory
428 # (i.e. ``CTEST_DASHBOARD_ROOT`` is set before call and that directory will be
429 # created if it does not already exist). In this case, there are typically
430 # two (partial) project source tree's, a) the "driver" skeleton source tree
431 # (typically with an embedded tribits/ directory) that bootstraps the testing
432 # process that contains the CTest -S driver script, and b) the full "source"
433 # tree that is (optionally) cloned and/or updated and is directly configured,
434 # build, and tested. This mode can also handle the case where the source tree
435 # is already set up in the location pointed to by `CTEST_SOURCE_DIRECTORY`_
436 # and `CTEST_DO_SUBMIT`_ is set to ``FALSE`` so this mode can get away with a
437 # single source tree and can handle a variety of use cases that may
438 # pre-manipulate the source tree before ``tribits_ctest_driver()`` is run.
439 #
440 # There are a few different directory locations that are significant for this
441 # script used in one or both of the modes described above:
442 #
443 # .. _TRIBITS_PROJECT_ROOT:
444 #
445 # ``TRIBITS_PROJECT_ROOT=<projectDir>``.
446 #
447 # The root directory to an existing source tree where the project's
448 # `<projectDir>/ProjectName.cmake`_ (defining the ``PROJECT_NAME``
449 # variable) and `<projectDir>/Version.cmake`_ files can be found. This
450 # can be set() in the CTest -S script or override as an env var. The
451 # default and env override is set for this during the include() of the
452 # module ``TribitsCTestDriverCore.cmake``.
453 #
454 # ``${PROJECT_NAME}_TRIBITS_DIR=<tribits-dir>``
455 #
456 # The base directory for the TriBITS system's various CMake modules,
457 # python scripts, and other files. By default this is assumed to be
458 # ``${TRIBITS_PROJECT_ROOT}/cmake/tribits``. This can be set() in the
459 # CTest -S script or overridden as an env var. The default and env
460 # override is set for this during the include() of
461 # ``TribitsCTestDriverCore.cmake``.
462 #
463 # .. _CTEST_DASHBOARD_ROOT:
464 #
465 # ``CTEST_DASHBOARD_ROOT=<dashboard-root-dir>``
466 #
467 # If set, this is the base directory where this script runs that clones
468 # the sources for the project. If this directory does not exist, it will
469 # be created. If provided as the special value ``PWD``, then the present
470 # working directory is used. If empty, then this var has no effect. This
471 # can be set() in CTest -S script before the call to
472 # ``tribits_ctest_driver()`` or override as an env var.
473 #
474 # .. _CTEST_SOURCE_NAME:
475 #
476 # ``CTEST_SOURCE_NAME=<src-dir-name>``
477 #
478 # The name of the source directory. This can be set() in the CTest -S
479 # script before the call to ``tribits_ctest_driver()`` or overridden as an
480 # env var. By default, this is set to ``${PROJECT_NAME}``.
481 #
482 # .. _CTEST_SOURCE_DIRECTORY:
483 #
484 # ``CTEST_SOURCE_DIRECTORY=<src-dir-full-path>``
485 #
486 # Built-in CTest variable that determines the location of the sources that
487 # are used to define packages, dependencies and configure, build, and test
488 # the software. This is a variable that CTest directly reads and must
489 # therefore be set. This is used to set `PROJECT_SOURCE_DIR`_ which is
490 # used by the TriBITS system. If ``CTEST_DASHBOARD_ROOT`` is set, then
491 # this is hard-coded internally to
492 # ``${CTEST_DASHBOARD_ROOT}/${CTEST_SOURCE_NAME}`` and will therefore
493 # override any value that might be set in the CTest -S driver script.
494 # However, if ``CTEST_DASHBOARD_ROOT`` is empty when
495 # ``TribitsCTestDriverCore.cmake`` is included(), then by default it set
496 # to ``${TRIBITS_PROJECT_ROOT}``. This can only be set() in the CTest -S
497 # driver script and is not overridden as an env var. The only way to
498 # override in the ENV is to indirectly set through
499 # ``${CTEST_DASHBOARD_ROOT}``.
500 #
501 # .. _CTEST_BINARY_DIRECTORY:
502 #
503 # ``CTEST_BINARY_DIRECTORY=<binary-dir-full-path>``
504 #
505 # Built-in CTest variable that determines the location of the binary tree
506 # where output from CMake/CTest is put. This is used to set to
507 # `PROJECT_BINARY_DIR`_ which is used by the TriBITS system and this
508 # variable is directly ready by CTest itself. If ``CTEST_DASHBOARD_ROOT``
509 # is set, then this is hard-coded internally to
510 # ``${CTEST_DASHBOARD_ROOT}/BUILD`` (overwriting any existing value of
511 # ``CTEST_BINARY_DIRECTORY``). If ``CTEST_BINARY_DIRECTORY`` is empty
512 # when ``TribitsCTestDriverCore.cmake`` is included(), then by default it
513 # set to ``$ENV{PWD}/BUILD``. ``CTEST_BINARY_DIRECTORY`` can not be
514 # overridden in the env.
515 #
516 # .. _Determining What Packages Get Tested (tribits_ctest_driver()):
517 #
518 # **Determining What Packages Get Tested (tribits_ctest_driver()):**
519 #
520 # Before any testing is done, the set of packages to be tested is determined.
521 # This determination uses the basic `TriBITS Dependency Handling Behaviors`_
522 # and logic. By default, the set of packages to be tested and otherwise
523 # explicitly processed is determined by the vars (which can also be set as env
524 # vars):
525 #
526 # .. _${PROJECT_NAME}_PACKAGES:
527 #
528 # ``${PROJECT_NAME}_PACKAGES=<pkg0>,<pkg1>,...``
529 #
530 # A semi-colon ';' or comma ',' separated list of packages that determines
531 # the specific set of packages to test. If left at the default value of
532 # empty "", then `${PROJECT_NAME}_ENABLE_ALL_PACKAGES`_ is set to ``ON``
533 # and that enables packages as described in `<Project>_ENABLE_ALL_PACKAGES
534 # enables all PT (cond. ST) packages`_. This variable can use ',' to
535 # separate package names instead of ';'. The default value is empty "".
536 #
537 # .. _${PROJECT_NAME}_ADDITIONAL_PACKAGES:
538 #
539 # ``${PROJECT_NAME}_ADDITIONAL_PACKAGES=<pkg0>,<pkg1>,...``
540 #
541 # If ``${PROJECT_NAME}_PACKAGES`` is empty (and therefore
542 # ``${PROJECT_NAME}_ENABLE_ALL_PACKAGES=ON`` is set), then additional
543 # packages not enabled in that logic can be listed
544 # ``${PROJECT_NAME}_ADDITIONAL_PACKAGES`` and they will be tested as well.
545 # For example, if this wold be used when there are some additional ST or
546 # EX packages that should be tested in a PT build
547 # (e.g. ``${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE=FALSE``. The
548 # default value is empty "".
549 #
550 # ``${PROJECT_NAME}_PACKAGE_ENABLES_FILE=<filepath>``
551 #
552 # A file that is expected to define a set to `set()` statements to enable a
553 # set of packages. The set of packages enabled will determine what
554 # packages are specifically processed and tested (according to other
555 # options as well). NOTE: To get this set of enables passed to inner
556 # configure, also list this file in the inner configure cache variable
557 # `${PROJECT_NAME}_CONFIGURE_OPTIONS_FILE`_ (see passing such options
558 # through in `Setting variables in the inner CMake configure
559 # (tribits_ctest_driver())`_). This is used instead of the variable
560 # ``${PROJECT_NAME}_PACKAGES`` to specify the set of packages to enable and
561 # test. (If both ``${PROJECT_NAME}_PACKAGES`` and
562 # ``${PROJECT_NAME}_PACKAGE_ENABLES_FILE`` are both set, then a fatal error
563 # will occur. The default value is empty "".
564 #
565 # .. _${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES:
566 #
567 # ``${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES=[TRUE|FALSE]``
568 #
569 # If set to ``TRUE``, then all of the downstream packages from those
570 # specified in ``${PROJECT_NAME}_PACKAGES`` will be enabled (see
571 # `<Project>_ENABLE_ALL_FORWARD_DEP_PACKAGES enables downstream
572 # packages/tests`_). The default value is ``FALSE`` unless
573 # ``CTEST_ENABLE_MODIFIED_PACKAGES_ONLY=TRUE`` is set in which case the
574 # default value is ``TRUE``.
575 #
576 # ``${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE=[TRUE|FALSE]``
577 #
578 # If set to ``TRUE``, then ST packages will get enabled in automated logic
579 # in the outer determination of what packages to get tested. This value
580 # also gets passed to the inner CMake configure. The default value is
581 # ``OFF``.
582 #
583 # .. _${PROJECT_NAME}_EXCLUDE_PACKAGES:
584 #
585 # ``${PROJECT_NAME}_EXCLUDE_PACKAGES=<pkg0>,<pkg1>,...``
586 #
587 # A semi-colon ';' or comma ',' separated list of packages **NOT** to
588 # enable when determining the set of packages to be tested. NOTE: Listing
589 # packages here will *not* disable the package in the inner CMake
590 # configure when using the package-by-packages approach. To do that, you
591 # will have to disable them in the variable EXTRA_CONFIGURE_OPTIONS (set
592 # in your driver script). But for the all-at-once approach this list of
593 # package disables **IS** pass into the inner configure.
594 #
595 # ``${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=[TRUE|FALSE]``
596 #
597 # If set to ``ON`` (or ``TRUE``), then if there are conflicts between
598 # explicit enables and disables then explicit disables will override the
599 # explicit enables (see `Disables trump enables where there is a
600 # conflict`_). The default is ``ON`` and likely should not be changed.
601 # The default value is ``ON``.
602 #
603 # .. _CTEST_EXPLICITLY_ENABLE_IMPLICITLY_ENABLED_PACKAGES:
604 #
605 # ``CTEST_EXPLICITLY_ENABLE_IMPLICITLY_ENABLED_PACKAGES=[TRUE|FALSE]``
606 #
607 # If set to ``TRUE``, then all of the upstream packages for those selected
608 # to be explicitly tested will be processed with results posted to CDash.
609 # The default is ``TRUE`` unless
610 # ``CTEST_ENABLE_MODIFIED_PACKAGES_ONLY==TRUE``. Most builds that specify
611 # a specific set of packages in ``${PROJECT_NAME}_PACKAGES`` should likely
612 # set this to ``FALSE``.
613 #
614 # NOTE: Any and all of the above vars can be set as env vars and they will
615 # override the value set inside the CTest -S script with ``set()``` (or
616 # `set_default()`_) statements. Also, for any of the vars that take a list,
617 # the CMake standard semi-colon char ';' can be used to separate list items or
618 # comas ',' can be used so that they can be used when setting env vars. (The
619 # comas ',' are then replaced with semi-colons ';' internally before
620 # interpreted as an list by CMake.)
621 #
622 # The other mode for selecting the set of packages to be tested is to only
623 # test the packages that have changes since the last time this build was run
624 # and testing packages that previously failed. That mode is turned on by the
625 # var:
626 #
627 # .. _CTEST_ENABLE_MODIFIED_PACKAGES_ONLY:
628 #
629 # ``CTEST_ENABLE_MODIFIED_PACKAGES_ONLY=[TRUE|FALSE]``
630 #
631 # If ``TRUE``, then only packages that have changes pulled from the git
632 # repos since the last time the build ran will be tested (in addition to
633 # packages that failed in the last build). If ``FALSE``, the set of
634 # packages to be tested is determined by `${PROJECT_NAME}_PACKAGES`_ and
635 # other variables as described above.
636 #
637 # .. _Setting variables in the inner CMake configure (tribits_ctest_driver()):
638 #
639 # **Setting variables in the inner CMake configure:**
640 #
641 # It is important to understand that none of the CMake vars that get set in
642 # the outer CTest -S program that calls ``tribits_ctest_driver()``
643 # automatically get passed into the inner configure of the TriBITS CMake
644 # project using the ``ctest_configure()`` command by CMake. From the
645 # perspective of raw CTest and CMake, these are completely separate programs.
646 # However, the ``tribits_ctest_driver()`` function will forward subset a of
647 # variables documented below into the inner CMake configure. The following
648 # variables that are set in the outer CTest -S program will be passed into the
649 # inner CMake configure by default (but their values they can be overridden by
650 # options listed in ``EXTRA_SYSTEM_CONFIGURE_OPTIONS`` or
651 # ``EXTRA_CONFIGURE_OPTIONS``):
652 #
653 # ``-D${PROJECT_NAME}_IGNORE_MISSING_EXTRA_REPOSITORIES=ON``
654 #
655 # Missing extra repos are always ignored in the inner CMake configure.
656 # This is because any problems reading an extra repo will be caught in the
657 # outer CTest -S driver script.
658 #
659 # ``-D${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON``
660 #
661 # Because of the behavior of the package-by-package mode, currently, this
662 # is hard-coded to ``ON``. (This set may be removed in the future for the
663 # all-at-once mode.)
664 #
665 # ``-D${PROJECT_NAME}_ALLOW_NO_PACKAGES:BOOL=ON``
666 #
667 # This is currently set for the package-by-package mode since some
668 # packages may get disabled because required upstream dependent packages
669 # may be disabled. (This set may be removed in the future for the
670 # all-at-once mode.)
671 #
672 # The following variables set in the outer CTest -S driver script will be passed
673 # down into the inner CMake configure through the ``OPTIONS`` variable to the
674 # ``ctest_configure()`` command:
675 #
676 # * ``${PROJECT_NAME}_TRIBITS_DIR``: Direct pass-through
677 # * ``${PROJECT_NAME}_WARNINGS_AS_ERRORS_FLAGS``: Direct pass-through
678 # * ``${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES``: Direct pass-through
679 # * ``${PROJECT_NAME}_DEPS_XML_OUTPUT_FILE``: Set to empty if
680 # ``CTEST_GENERATE_DEPS_XML_OUTPUT_FILE==FALSE``
681 # * ``${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE``: Direct pass-through
682 # * ``${PROJECT_NAME}_ENABLE_TESTS``: Set the the same value as
683 # `${PROJECT_NAME}_INNER_ENABLE_TESTS`_ set in the outer ctest -S driver script
684 # * ``${PROJECT_NAME}_SKIP_CTEST_ADD_TEST``: Direct pass-through
685 # * ``MPI_EXEC_MAX_NUMPROCS``: Direct pass-through
686 # * ``${PROJECT_NAME}_ENABLE_COVERAGE_TESTING``: Set to ``ON`` if
687 # ``CTEST_DO_COVERAGE_TESTING==TRUE``
688 # * ``${PROJECT_NAME}_EXTRAREPOS_FILE``: Set to empty if
689 # ``${PROJECT_NAME}_EXTRAREPOS_FILE=NONE``. Otherwise, passed through.
690 # * ``${PROJECT_NAME}_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE``: Direct pass-through
691 # * `${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES`_: Only passed down if
692 # non-empty value is set (default empty "")
693 #
694 # Arbitrary options can be set to be passed into the inner CMake configure
695 # after the above options are passed by setting the following variables:
696 #
697 # .. _EXTRA_SYSTEM_CONFIGURE_OPTIONS:
698 #
699 # ``EXTRA_SYSTEM_CONFIGURE_OPTIONS``
700 #
701 # Additional list of system-specific options to be passed to the inner
702 # CMake configure. This must be set in the CTest -S driver script with a
703 # ``set()`` statement (i.e. env var is not read). These options get added
704 # after all of the above pass-through options so they can override any of
705 # those options. **WARNING:** Do not include any semicolons ';' in these
706 # arguments (see below WARNING).
707 #
708 # .. _EXTRA_CONFIGURE_OPTIONS:
709 #
710 # ``EXTRA_CONFIGURE_OPTIONS``
711 #
712 # Additional list of extra cmake configure options to be passed to the
713 # inner CMake configure. This must be set in the CTest -S driver script
714 # with a ``set()`` statement (i.e. env var is not read). These options
715 # get added after all of the above pass-through options and the options
716 # listed in ``EXTRA_SYSTEM_CONFIGURE_OPTIONS`` so they can override any of
717 # those options. **WARNING:** Do not include any semicolons ';' in these
718 # arguments (see below WARNING).
719 #
720 # ``${PROJECT_NAME}_EXTRA_CONFIGURE_OPTIONS``:
721 #
722 # A yet additional list of extra cmake configure options to be passed to
723 # the inner CMake configure after all of the others. Unlike the above
724 # options, this var is read from the env and allows the user to set
725 # arbitrary configure options that overrides all others. **WARNING:** Do
726 # not include any semicolons ';' in these arguments (see below WARNING).
727 #
728 # These configure options are passed into the ``ctest_configure()`` command in
729 # the order::
730 #
731 # <initial options> ${EXTRA_SYSTEM_CONFIGURE_OPTIONS}} \
732 # ${EXTRA_CONFIGURE_OPTIONS} ${${PROJECT_NAME}_EXTRA_CONFIGURE_OPTIONS}
733 #
734 # **WARNING:** The options listed in ``EXTRA_SYSTEM_CONFIGURE_OPTIONS``,
735 # ``EXTRA_CONFIGURE_OPTIONS``, and ``${PROJECT_NAME}_EXTRA_CONFIGURE_OPTIONS``
736 # should not contain any semi-colons ';' or they will be interpreted as array
737 # bounds and mess up the arguments when passed to the inner CMake configure.
738 # To avoid problems with spaces and semicolons, it is usually a good idea to
739 # put these cache vars into ``*.cmake`` file fragments and the pass them
740 # through using the variable `<Project>_CONFIGURE_OPTIONS_FILE`_ as::
741 #
742 # -D<Project>_CONFIGURE_OPTIONS_FILE=<optionsfile1>.cmake,<optionsfile2>.cmake,...
743 #
744 # or using the built-in CMake option::
745 #
746 # -C<abs-base>/<optionsfile1>.cmake -C<abs-base>/<optionsfile2>.cmake ...
747 #
748 # NOTE: The full list of options passed into the inner CMake is printed out
749 # before calling ``ctest_configure()`` so any issues setting options and the
750 # ordering of options can be seen in that printout.
751 #
752 # .. _Determining what testing-related actions are performed (tribits_ctest_driver()):
753 #
754 # **Determining what testing-related actions are performed (tribits_ctest_driver()):**
755 #
756 # When run, ``tribits_ctest_driver()`` always performs a configure and build
757 # but other actions are optional. By default, a version control update (or
758 # clone) is performed as well as running tests and submitting results to
759 # CDash. But the version control update, the running tests and submitting
760 # results to CDash can be disabled. Also, coverage testing and memory testing
761 # are not performed by default but they can be turned on with results
762 # submitted to CDash. These actions are controlled by the following variables
763 # (which can be set in the CTest -S script before calling
764 # ``tribits_ctest_driver()`` and can be overridden by env vars of the same
765 # name):
766 #
767 # .. _CTEST_DO_NEW_START:
768 #
769 # ``CTEST_DO_NEW_START=[TRUE|FALSE]``
770 #
771 # If ``TRUE``, ``ctest_start()`` is called to set up a new "dashboard"
772 # (i.e. define a new CDash build with a unique Build Stamp defined in the
773 # ``Testing/TAG`` file). If ``FALSE``, then ``ctest_start(... APPEND)``
774 # is called which allows it this ctest -S invocation to append results to
775 # an existing CDash build. (See ???). Default ``TRUE``.
776 #
777 # ``CTEST_DO_UPDATES=[TRUE|FALSE]``
778 #
779 # If ``TRUE``, then the source repos will be updated as specified in
780 # `Repository Updates (tribits_ctest_driver())`_. Default ``TRUE``.
781 #
782 # .. _CTEST_UPDATE_ARGS:
783 #
784 # ``CTEST_UPDATE_ARGS``
785 #
786 # Any extra arguments to use with ``git clone`` to clone the base git repo.
787 # The default value is empty "". This is only used for the base git repo
788 # (not the extra repos).
789 #
790 # .. _CTEST_UPDATE_VERSION_ONLY:
791 #
792 # ``CTEST_UPDATE_VERSION_ONLY``:
793 #
794 # Built-in CTest variable that if set to ``TRUE`` will change the default
795 # behavior of ``ctest_update()`` such that it will not clone or pull from
796 # the remove repo or update the local branch in any way. This also skips
797 # any actions on extra repos and skips the creation of the ``Updates.txt``
798 # or ``UpdateCommandsOutput.txt`` files. Setting this to ``TRUE`` along
799 # with ``CTEST_DO_UPDATES=ON`` and doing a submit to CDash will result
800 # "Revision" column being present with the Git SHA1 of the base repo (and a
801 # hyperlink to the commit in the public git repo). This is useful when
802 # using with a CI testing system that handles all of the git repo
803 # manipulation like GitHub Actions, GitLab CI, or Jenkins.
804 #
805 # .. _CTEST_START_WITH_EMPTY_BINARY_DIRECTORY:
806 #
807 # ``CTEST_START_WITH_EMPTY_BINARY_DIRECTORY=[TRUE|FALSE]``
808 #
809 # If ``TRUE``, then if the binary directory ``${CTEST_BINARY_DIRECTORY}``
810 # already exists, then it will be clean out using the CTest command
811 # ``ctest_empty_binary_directory()``. However, this can set to ``FALSE``
812 # in which case a rebuild (using existing object files, libraries, etc.)
813 # will be performed which is useful when using an incremental CI server.
814 # But this is ignored if ``CTEST_DO_NEW_START=FALSE``. Default ``TRUE``
815 # (which is the most robust option).
816 #
817 # .. _CTEST_DO_CONFIGURE:
818 #
819 # ``CTEST_DO_CONFIGURE=[TRUE|FALSE]``
820 #
821 # If ``TRUE``, then the selected packages will be configured. If
822 # ``FALSE``, it is assumed that a relevant configure is already in place
823 # in the binary directory if a build or running tests is to be done. Note
824 # that for the package-by-package mode, a configure is always done if a
825 # build or any testing is to be done but results will not be sent to CDash
826 # unless ``CTEST_DO_CONFIGURE=TRUE``. Default ``TRUE``.
827 #
828 # .. _CTEST_WIPE_CACHE:
829 #
830 # ``CTEST_WIPE_CACHE=[TRUE|FALSE]``
831 #
832 # If ``TRUE``, then ``${CTEST_BINARY_DIRECTORY}/CMakeCache.txt`` and
833 # ``${CTEST_BINARY_DIRECTORY}/CMakeFiles/`` will be deleted before
834 # performing a configure. (This value is set to ``FALSE`` by the `make
835 # dashboard`_ target that does an experimental build, test, and submit to
836 # CDash.) Default ``TRUE`` (which is the most robust option in general).
837 #
838 # .. _CTEST_DO_BUILD:
839 #
840 # ``CTEST_DO_BUILD=[TRUE|FALSE]``
841 #
842 # If ``TRUE``, then the selected packages will be build. If ``FALSE``, it
843 # is assumed that a relevant build is already in place in the binary
844 # directory if any testing is to be done. Default ``TRUE``.
845 #
846 # .. _CTEST_BUILD_FLAGS:
847 #
848 # ``CTEST_BUILD_FLAGS``
849 #
850 # Built-in CTest variable that gives the flags passed to the build command
851 # called inside of the built-in CTest command ``ctest_build()``. The
852 # default is ``-j2`` when `CTEST_CMAKE_GENERATOR`_ is set to ``Unix
853 # Makefiles``. Otherwise, the default is empty "". Useful options to set
854 # are ``-j<N>`` (to build on parallel) and ``-k`` (to keep going when
855 # there are build errors so we can see all of the build errors). When
856 # ``CTEST_CMAKE_GENERATOR`` is set to ``Ninja``, the ``j<N>`` option can
857 # be left off (in which case all of the available unloaded cores are used
858 # to build) and the option ``-k 999999`` can be used to build all targets
859 # when there are build failures.
860 #
861 # .. _CTEST_DO_INSTALL:
862 #
863 # ``CTEST_DO_INSTALL=[TRUE|FALSE]``
864 #
865 # If ``TRUE``, then ``-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON`` will be
866 # passed th the inner CMake configure and the 'install_package_by_package'
867 # target will be built to install what has been configured and built by
868 # the build step for the all-at-once mode
869 # (i.e. ``${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE=TRUE``). If ``FALSE``,
870 # then ``-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON`` is **not** added to the
871 # inner configure and no install is performed. (NOTE: The cmake var
872 # ``CMAKE_INSTALL_PREFIX`` must be set on the inner cmake configure for
873 # this to work correctly. Also, the install is currently not implemented
874 # for the package-by-package mode
875 # ``${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE=FALSE`` and this option will
876 # simply be ignored in that case.) Default ``FALSE``.
877 #
878 # .. _CTEST_DO_TEST:
879 #
880 # ``CTEST_DO_TEST=[TRUE|FALSE]``
881 #
882 # If ``TRUE``, then ``ctest_test()`` will be called and test results will
883 # be submitted to CDash. This should be set to ``FALSE`` when one wanted
884 # to only test the configure and build of a project but not run any tests
885 # (e.g. when cross compiling or if the tests are too expensive to run).
886 # The default value is ``TRUE``.
887 #
888 # .. _CTEST_PARALLEL_LEVEL:
889 #
890 # ``CTEST_PARALLEL_LEVEL=<num>``
891 #
892 # The parallel level passed in the ``PARALLEL_LEVEL`` argument to
893 # ``ctest_test()`` AND ``ctest_memcheck()``. The default value is ``1``
894 # (one).
895 #
896 # .. _${PROJECT_NAME}_INNER_ENABLE_TESTS:
897 #
898 # ``${PROJECT_NAME}_INNER_ENABLE_TESTS``
899 #
900 # If ``OFF``, then ``${PROJECT_NAME}_ENABLE_TESTS=OFF`` will be passed to
901 # the inner CMake configure. This will avoid building of all tests and
902 # examples for the enabled packages and also no CTest tests will be
903 # defined using calls to ``add_test()`` in the inner project configure.
904 # This results in just the building of the libraries and non-test,
905 # non-example executables (which will be much faster for some projects).
906 # The default value is ``ON`` (in which case all of the test and example
907 # executable and other targets will get built for all of the explicitly
908 # enabled packages and the associated ctest tests will be defined and
909 # run).
910 #
911 # .. _${PROJECT_NAME}_SKIP_CTEST_ADD_TEST:
912 #
913 # ``${PROJECT_NAME}_SKIP_CTEST_ADD_TEST``:
914 #
915 # If set to ``TRUE``, then ``${PROJECT_NAME}_SKIP_CTEST_ADD_TEST=TRUE`` is
916 # passed in to the inner CMake configure. This will result in all of the
917 # test and example executables for the enabled packages to be built but no
918 # ctest tests will get defined and run by skipping the inner CMake calls
919 # to ``add_test()``. Setting this to ``TRUE`` allows all of the
920 # libraries, production executables and the test and example executables
921 # and other targets to get built, but no tests will be run. However, when
922 # ``CTEST_DO_TEST=ON``, the ``ctest_test()`` command will still be run and
923 # test results will still be submitted to CDash which will report zero
924 # tests. This avoids the test results being reported as missing on CDash
925 # for tools like ``ctest_analyze_and_report.py``. The default value is
926 # ``FALSE`` (in which case any enabled tests or examples in the explicitly
927 # enabled packages will get run).
928 #
929 # .. _CTEST_DO_COVERAGE_TESTING:
930 #
931 # ``CTEST_DO_COVERAGE_TESTING=[TRUE|FALSE]``
932 #
933 # If ``TRUE``, then ``ctest_coverage()`` is called to collect coverage and
934 # submit results generated from the previous ``ctest_test()`` command.
935 # Setting this to ``TRUE`` also results in
936 # ``-D${PROJECT_NAME}_ENABLE_COVERAGE_TESTING=ON`` getting passed down to
937 # the inner CMake configure of the project (i.e. so that the executables
938 # are instrumented to generate coverage data when run by the tests in the
939 # ``ctest_test()`` command). (Default is ``OFF``)
940 #
941 # .. _CTEST_COVERAGE_COMMAND:
942 #
943 # ``CTEST_COVERAGE_COMMAND``
944 #
945 # Built-in CTest variable that determines the command that is run by
946 # ``ctest_coverage()`` to collect coverage results. That default value is
947 # ``gcov``.
948 #
949 # .. _CTEST_DO_MEMORY_TESTING:
950 #
951 # ``CTEST_DO_MEMORY_TESTING=[TRUE|FALSE]``
952 #
953 # If ``TRUE``, then ``ctest_memcheck()`` is called to run the test suite
954 # with the memory checking tool and results submitted to CDash.
955 #
956 # .. _CTEST_MEMORYCHECK_COMMAND:
957 #
958 # ``CTEST_MEMORYCHECK_COMMAND``
959 #
960 # Built-in CTest variable that determines the command that is used to run
961 # the command for each test run by the ``ctest_memcheck()`` command. If
962 # ``valgrind`` is found on the local system, then that is used by default.
963 # Otherwise, the default is empty "".
964 #
965 # .. _CTEST_MEMORYCHECK_COMMAND_OPTIONS:
966 #
967 # ``CTEST_MEMORYCHECK_COMMAND_OPTIONS``
968 #
969 # Built-in CTest variable that determines what options are passed to the
970 # memory checking command before the actual test command. The default
971 # value is empty "".
972 #
973 # .. _CTEST_GENERATE_OUTER_DEPS_XML_OUTPUT_FILE:
974 #
975 # ``CTEST_GENERATE_OUTER_DEPS_XML_OUTPUT_FILE=[TRUE|FALSE]``
976 #
977 # If ``TRUE``, then ``<Project>PackageDependencies.xml`` file will be
978 # generated in the outer CTest -S program. This file is used to help
979 # determine what packages have changed and need to be tested when in CI
980 # mode (e.g. when ``CTEST_ENABLE_MODIFIED_PACKAGES_ONLY=TRUE`` is set).
981 # It is also needed to generate the ``CDashSubprojectDependencies.xml``
982 # file that gets submitted to CDash to inform it of the list of
983 # subprojects and subproject dependencies (i.e. TriBITS packages). The
984 # default value is ``TRUE``.
985 #
986 # .. _CTEST_SUBMIT_CDASH_SUBPROJECTS_DEPS_FILE:
987 #
988 # ``CTEST_SUBMIT_CDASH_SUBPROJECTS_DEPS_FILE=[TRUE|FALSE]``
989 #
990 # If ``TRUE``, then CDash subprojects XML file is generated and submitted
991 # to CDash. This file tells CDash about the subproject (i.e. TriBITS
992 # package) structure. The default value is ``TRUE``.
993 #
994 # .. _CTEST_DO_SUBMIT:
995 #
996 # ``CTEST_DO_SUBMIT=[TRUE|FALSE]``
997 #
998 # If ``TRUE``, then all of the results generated locally are submitted to
999 # CDash using ``ctest_submit()``. One can set this to ``FALSE`` when
1000 # locally debugging a CTest -S driver script to avoid spamming CDash. The
1001 # default value is ``TRUE``. (NOTE: This may submit to more than one
1002 # CDash site as noted in `Specifying where the results go to CDash
1003 # (tribits_ctest_driver())`_).
1004 #
1005 # .. _Determining how the results are displayed on CDash (tribits_ctest_driver()):
1006 #
1007 # **Determining how the results are displayed on CDash (tribits_ctest_driver()):**
1008 #
1009 # These options all primarily determine how VC update, configure, build, test,
1010 # and other results submitted are displayed on CDash (but not what CDash
1011 # site(s) or project(s) to which they are submitted, see `Specifying where the
1012 # results go to CDash (tribits_ctest_driver())`_). These options can all be
1013 # set in the CTest -S script using ``set()`` statements before
1014 # ``tribits_ctest_driver()`` is called and can be overridden in the env when
1015 # running the CTest -S driver script.
1016 #
1017 # .. _CTEST_TEST_TYPE:
1018 #
1019 # ``CTEST_TEST_TYPE=[Nightly|Continuous|Experimental]``
1020 #
1021 # Determines the model for build. This value is passed in as the first
1022 # argument to the built-in CTest function ``ctest_start()``. Valid values
1023 # include ``Nightly``, ``Continuous``, and ``Experimental``. As far as
1024 # CTest is concerned, the only real impact this CTest "Model" has is on
1025 # setting the time stamp in the build stamp field (which is stored in the
1026 # file ``Testing/TAG``). For the model ``Nightly``, the time stamp in the
1027 # build stamp is taken from the variable ``CTEST_NIGHTLY_START_TIME`` read
1028 # in from the file `<projectDir>/CTestConfig.cmake`_ file. Otherwise, the
1029 # time stamp used is the current build start time. (The reason this is
1030 # significant is that builds on CDash that have the same site, buildname,
1031 # and build stamp are considered the same build and will combine results.)
1032 # This also defines the default value for `${PROJECT_NAME}_TRACK`_ (see
1033 # below) as well as defines the default value for
1034 # ``${PROJECT_NAME}_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE``. The default value
1035 # is ``Experimental``.
1036 #
1037 # .. _${PROJECT_NAME}_TRACK:
1038 #
1039 # ``${PROJECT_NAME}_TRACK=<cdash-group>``
1040 #
1041 # Specifies the testing track that specifies the CDash group for which
1042 # results are displayed under (i.e. the "Group" filter field on CDash).
1043 # This is the value used for the (deprecated) ``TRACK`` argument (renamed
1044 # ``GROUP`` in CMake/CTest versions 3.16+) of the built-in CTest function
1045 # ``ctest_start()``. The default value is set to ``${CTEST_TEST_TYPE}``.
1046 # However, if ``CTEST_TEST_TYPE==Experimental`` (or ``EXPERIMENTAL``),
1047 # then ``${PROJECT_NAME}_TRACK`` is forced to ``Experimental``, even if it
1048 # was set to a different value. The default value can also be set in the
1049 # ctest -S driver script itself by setting ``set(${PROJECT_NAME}_TRACK
1050 # <cdash-group>)``. And, of course, if the environment variable ``export
1051 # <Project>_TRACK=<cdash-group>`` is set, then that value will be used for
1052 # the CDash Track/Group to submit results to.
1053 #
1054 # .. _CTEST_SITE:
1055 #
1056 # ``CTEST_SITE=<site-name>``
1057 #
1058 # This is a built-in CTest variable that determines what is displayed for
1059 # the ``site`` field for the build on CDash. This specified by default by
1060 # calling the built-in CMake/CTest function ``site_name()``.
1061 #
1062 # .. _COMPILER_VERSION:
1063 #
1064 # ``COMPILER_VERSION=<compiler-version>``
1065 #
1066 # Gives the name of the compiler that is used to compose a default
1067 # `CTEST_BUILD_NAME`_. If ``CTEST_BUILD_NAME`` is explicitly set, then
1068 # this value is ignored.
1069 #
1070 # .. _CTEST_BUILD_NAME:
1071 #
1072 # ``CTEST_BUILD_NAME=<build-name>``
1073 #
1074 # This is a built-in CTest variable that determines the name of the build
1075 # on CDash. Builds that have the same ``CTEST_SITE``,
1076 # ``CTEST_BUILD_NAME`` and ``${PROJECT_NAME}_TRACK`` are considered to be
1077 # related builds and CDash will relate them as "previous" and "next"
1078 # builds (good for showing number of added or removed tests, new test
1079 # failures, new passing tests, etc.). If not specified, it is given the
1080 # default value ``${HOST_TYPE}-${COMPILER_VERSION}-${BUILD_DIR_NAME}``.
1081 # Here, ``HOST_TYPE`` is determined automatically from the ``uname``
1082 # system command using ``find_program(uname)``. The value of
1083 # ``BUILD_DIR_NAME`` is expected to be set in each specific CTest -S
1084 # driver script.
1085 #
1086 # .. _CTEST_NOTES_FILES:
1087 #
1088 # ``CTEST_NOTES_FILES="<filepath1>;<filepath2>;..."``
1089 #
1090 # Built-in CTest variable that specifies a semi-colon separated list of
1091 # files that will get uploaded to CDash as "notes files". This function
1092 # will also add notes files as well such as the file
1093 # ``CMakeCache.clean.txt`` (cleaned-up version of the CMakeCache.txt
1094 # file), the file ``Updates.txt`` (lists new git commits pulled in all the
1095 # git repos), the file ``UpdateCommandsOutput.txt`` (list of commands and
1096 # their output which are run by ``ctest_update()`` in the base git repo),
1097 # and the file ``${PROJECT_NAME}RepoVersion.txt`` (gives version of all
1098 # the git repos being tested).
1099 #
1100 # .. _CTEST_CHANGE_ID:
1101 #
1102 # ``CTEST_CHANGE_ID``
1103 #
1104 # Built-in CTest variable that can be used to set to an integer for the
1105 # GitHub Pull Request (PR) ID or GitLab Merge Request (MR) ID (or other
1106 # such repository and development management system's change control ID).
1107 # If the CDash project is properly configured to point to the GitHub or
1108 # GitLab (or other supported) repository for the project, then CDash will
1109 # put a hyper-linked icon beside the build name that links back to the PR
1110 # or MR issue with that ID. It may also be used for other purposes as
1111 # well in the future.
1112 #
1113 # .. _Specifying where the results go to CDash (tribits_ctest_driver()):
1114 #
1115 # **Specifying where the results go to CDash (tribits_ctest_driver()):**
1116 #
1117 # By default, the target CDash server and CDash project are specified by the
1118 # variables set in the file `<projectDir>/CTestConfig.cmake`_; specifically,
1119 # ``CTEST_DROP_SITE``, ``CTEST_PROJECT_NAME``, and ``CTEST_DROP_LOCATION``.
1120 # If these are set using `set_default_and_from_env()`_, as shown in the
1121 # example ``TribitsExampleProject/CTestConfig.cmake`` file, then they can be
1122 # overridden with ``set()`` statements in the CTest -S script or as env vars;
1123 # simple enough.
1124 #
1125 # In addition, results can be sent to a second CDash site using the variables:
1126 #
1127 # ``TRIBITS_2ND_CTEST_DROP_SITE``
1128 #
1129 # CDash drop site for second upload of results. If empty, then
1130 # ``CTEST_DROP_SITE`` is used.
1131 #
1132 # ``TRIBITS_2ND_CTEST_DROP_LOCATION``
1133 #
1134 # Location for the second drop site. If empty, then
1135 # ``CTEST_DROP_LOCATION`` is used.
1136 #
1137 # At lease one of these vars must be set to non empty or a second submit will
1138 # not be performed. For more details, see `TRIBITS_2ND_CTEST_DROP_SITE`_ and
1139 # `TRIBITS_2ND_CTEST_DROP_LOCATION`_.
1140 #
1141 # .. _Links to results on CDash (tribits_ctest_driver()):
1142 #
1143 # **Links to results on CDash (tribits_ctest_driver()):**
1144 #
1145 # Links to where the results will be posted on CDash are printed to STDOUT
1146 # before it performs any actions and at end after all of the actions and
1147 # submits have been completed.
1148 #
1149 # The results are printed to STDOUT in a section that looks like::
1150 #
1151 # Link to this build's results on CDash:
1152 #
1153 # <cdash-build-url>
1154 #
1155 # Link to all builds for this repo version on CDash:
1156 #
1157 # <cdash-revision-builds-url>
1158 #
1159 # Link to all nonpassing tests for all builds for this repo version on CDash:
1160 #
1161 # <cdash-revision-nonpassing-tests-url>
1162 #
1163 # The URL ``<cdash-build-url>`` is created from the buildname, site, and
1164 # buildstartime fields which is known from the TAG file created by CTest.
1165 # This allows access the results for this particular build on CDash by just
1166 # clicking that link.
1167 #
1168 # The URL ``<cdash-revision-builds-url>`` provides a link to a CDash
1169 # ``index.php`` query that includes all of the builds with the same base Git
1170 # repo SHA1. This allows comparing the results of this build for other builds
1171 # for this same version of the base Git repository.
1172 #
1173 # The URL ``<cdash-revision-nonpassing-tests-url>`` gives a link to a CDash
1174 # ``queryTests.php`` query for all of the nonpassing tests for all of the
1175 # builds with this same base project Git repo SHA1. This allows comparing
1176 # test failures across all of the builds for the same base project Git repo
1177 # version.
1178 #
1179 # NOTE: The links ``<cdash-revision-builds-url>`` and
1180 # ``<cdash-revision-nonpassing-tests-url>`` are only provided if the base
1181 # project Git repo has the ``.git/`` subdirectory and if ``git log``
1182 # successfully returns the SHA1 for that base Git repo.
1183 #
1184 # NOTE: The links ``<cdash-revision-builds-url>`` and
1185 # ``<cdash-revision-nonpassing-tests-url>`` only consider the Git SHA1 of the
1186 # base project Git repo. For multi-repo projects (see `Multi-Repository
1187 # Support`_), you may get results for builds with different subrepo versions
1188 # and therefore may be comparing apples and oranges. (Projects that commit a
1189 # ``<Project>SubRepoVersion.txt`` file to their base Git repo or use Git
1190 # Submodules will have unique base project Git repo SHA1s for different
1191 # versions of the project's repos.)
1192 #
1193 # In addition, a text file ``CDashResults.txt`` will be written in the build
1194 # directory that contains this same CDash link information shown above. This
1195 # allows a process to cat the file ``CDashResults.txt`` to get links to the
1196 # results on CDash.
1197 #
1198 # .. _Determining what TriBITS repositories are included (tribits_ctest_driver()):
1199 #
1200 # **Determining what TriBITS repositories are included (tribits_ctest_driver()):**
1201 #
1202 # This script is set up to process extra VC and TriBITS repos that contribute
1203 # additional TriBITS packages to the base TriBITS project. This set of extra
1204 # repos is determined using the following vars (which can be set in the CTest
1205 # -S script or overridden with env vars of the same name):
1206 #
1207 # ``${PROJECT_NAME}_EXTRAREPOS_FILE=<extrarepos-file-path>``
1208 #
1209 # Points to a file that lists the extra VC and TriBITS repos. If not
1210 # explicitly set, then by default it will read from the file
1211 # `<projectDir>/cmake/ExtraRepositoriesList.cmake`_ unless
1212 # ``${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE=TRUE`` is set in the
1213 # ``ProjectName.cmake`` file in which case no extra repos file is read in.
1214 # See `<Project>_EXTRAREPOS_FILE`_.
1215 #
1216 # ``${PROJECT_NAME}_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE=[Nightly|Continuous|Experimental]``
1217 #
1218 # The category of extra repos to process from the file
1219 # ``${PROJECT_NAME}_EXTRAREPOS_FILE`` (see
1220 # `<Project>_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE`_).
1221 #
1222 # ``${PROJECT_NAME}_PRE_REPOSITORIES=<reponame1>,<reponame2>,...``
1223 #
1224 # Subset of "pre" extra repos specified in the file
1225 # ``${PROJECT_NAME}_EXTRAREPOS_FILE`` to process (see
1226 # `<Project>_PRE_REPOSITORIES`_).
1227 #
1228 # ``${PROJECT_NAME}_EXTRA_REPOSITORIES=<reponame1>,<reponame2>,...``
1229 #
1230 # Subset of "post" extra repos specified in the file
1231 # ``${PROJECT_NAME}_EXTRAREPOS_FILE`` to process (see
1232 # `<Project>_EXTRA_REPOSITORIES`_).
1233 #
1234 # The behavior for selecting extra repos using these variables is determined
1235 # as described in:
1236 #
1237 # * `Enabling extra repositories through a file`_
1238 #
1239 # .. _All-at-once versus package-by-package mode (tribits_ctest_driver()):
1240 #
1241 # **All-at-once versus package-by-package mode (tribits_ctest_driver()):**
1242 #
1243 # This function supports driving the configure, build, testing, and submitting
1244 # to CDash of the packages in the TriBITS project either all-at-once or
1245 # package-by-package, based on the vars (which can be set in the CTest -S
1246 # script and overridden by env vars):
1247 #
1248 # ``${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE=[TRUE|FALSE]``
1249 #
1250 # If ``TRUE``, then single calls to ``ctest_configure()``,
1251 # ``ctest_build()`` and ``ctest_test()`` are made for all of the packages
1252 # to be tested all at once with ``ctest_submit()`` called after each of
1253 # these. If ``FALSE`` then ``ctest_configure()``, ``ctest_build()`` and
1254 # ``ctest_test()`` and ``ctest_submit()`` are called in a loop, once for
1255 # each package to be explicitly tested.
1256 #
1257 # Both the all-at-once mode and the package-by-package mode should produce
1258 # equivalent builds of the project and submits to CDash (for correctly
1259 # constructed TriBITS projects and packages). But the package-by-package mode
1260 # will disable packages with failing library builds when processing downstream
1261 # packages, and therefore reduce the propagation of failures to downstream
1262 # packages and therefore is more robust. But the package-by-package mode is
1263 # more expensive in several respects for many projects.
1264 #
1265 # For newer versions of CDash 3.1+, for the all-at-once mode, the CDash server
1266 # will break down build and test results on a package-by-package basis on
1267 # CDash together.
1268 #
1269 # .. _Multiple ctest -S invocations (tribits_ctest_driver()):
1270 #
1271 # **Multiple ctest -S invocations (tribits_ctest_driver()):**
1272 #
1273 # By default, this function is meant to be used in a single invocation of the
1274 # ``ctest -S <script>.cmake`` command in order to do everything from the
1275 # beginning and submit to CDash. But there are times when one needs to do the
1276 # various steps in multiple ``ctest -S`` invocations that all send data to the
1277 # same CDash build. For example, on some clusters, configure and build must
1278 # be done on "compile nodes" but the tests must be run on "compute nodes".
1279 # Typically, these types of machines have a shared file system. On a system
1280 # like this, one would use two different invocations as::
1281 #
1282 # # Start new dashboard, update, configure, and build on compile node
1283 # env CTEST_DO_TEST=OFF \
1284 # ctest -S <script>.cmake
1285 #
1286 # # Run tests only on compute node
1287 # <run-on-compute-node> \
1288 # env CTEST_DO_NEW_START=OFF CTEST_DO_UPDATES=OFF \
1289 # CTEST_DO_CONFIGURE=OFF CTEST_DO_BUILD=OFF \
1290 # CTEST_DO_TEST=ON \
1291 # ctest -S <script>.cmake
1292 #
1293 # Above, `CTEST_DO_NEW_START`_ ``= OFF`` is needed to ensure that the test
1294 # results go to the same CDash build. (NOTE: A CDash build is uniquely
1295 # determined by the site name, build name and build stamp.)
1296 #
1297 # This approach works for both the all-at-once mode and the package-by-package
1298 # mode.
1299 #
1300 # Also, one can run each of the basic steps in its own ``ctest -S`` invocation
1301 # starting with ``CTEST_DO_NEW_START = ON``, then `CTEST_DO_UPDATES`_ ``=
1302 # ON``, then `CTEST_DO_CONFIGURE`_ ``= ON``, then `CTEST_DO_BUILD`_ ``= ON``,
1303 # then then `CTEST_DO_TEST`_ ``= ON``, etc. While there is typically no
1304 # reason to split things up to this level of granularity, CTest and this
1305 # ``tribits_ctest_driver()`` function will support such usage. All that is
1306 # required is that those steps be performed in that order. For example, one
1307 # cannot do a build in one ``ctest -S`` invocation and then try to do a
1308 # configure in the next because the build will fail because a valid
1309 # configuration has not been performed yet. And one cannot run just tests if
1310 # there is not a valid configuration and build already in place.
1311 #
1312 # .. _Repository Updates (tribits_ctest_driver()):
1313 #
1314 # **Repository Updates (tribits_ctest_driver()):**
1315 #
1316 # Like the rest of TriBITS, ``ctest -S`` scripts written using this function
1317 # support a collection of extra repositories in addition to the base git
1318 # repository.
1319 #
1320 # Whether the local repos are updated (or left as is) is determined by the
1321 # variable:
1322 #
1323 # .. _CTEST_DO_UPDATES:
1324 #
1325 # ``CTEST_DO_UPDATES=[TRUE|FALSE]``
1326 #
1327 # If set to ``TRUE``, then each of the git repos will be cloned if they do
1328 # not already exist and if already present will be updated as described
1329 # below (and will wipe out any local changes). If set to ``FALSE``, then
1330 # the git repos will be left alone and must therefore already be cloned and
1331 # updated at the desired state. For example, this should be set to
1332 # ``FALSE`` when running against a local development repo (e.g. the `make
1333 # dashboard`_ target sets this to ``FALSE`` automatically) or when other
1334 # logic is used to setup the source directories. **WARNING:** If you are
1335 # running against a local repo with local changes and you don't set to
1336 # ``FALSE``, then your local uncommitted changes will be wiped out and the
1337 # local branch will be hard reset to the remote tracking branch! The
1338 # default value is ``TRUE``.
1339 #
1340 # **WARNING:** If you don't want local changes in your git repos to get blown
1341 # away, then set ``CTEST_DO_UPDATES`` to ``FALSE``!
1342 #
1343 # If the base repo pointed to by ``${CTEST_SOURCE_DIRECTORY}`` is missing, it
1344 # cloned inside of the ``ctest_start()`` function using the custom command::
1345 #
1346 # git clone [-b ${${PROJECT_NAME}_BRANCH}] \
1347 # -o ${${PROJECT_NAME}_GIT_REPOSITORY_REMOTE} \
1348 # ${${PROJECT_NAME}_REPOSITORY_LOCATION}
1349 #
1350 # where:
1351 #
1352 # .. _${PROJECT_NAME}_REPOSITORY_LOCATION:
1353 #
1354 # ``${PROJECT_NAME}_REPOSITORY_LOCATION=<repo-url>``
1355 #
1356 # The URL of the base git repo ``<repo-url>`` to clone inside of
1357 # ``ctest_start()``. The default is
1358 # ``${${PROJECT_NAME}_REPOSITORY_LOCATION_NIGHTLY_DEFAULT}`` when
1359 # ``CTEST_TEST_TYPE=Nightly`` and otherwise the default is
1360 # ``${${PROJECT_NAME}_REPOSITORY_LOCATION_DEFAULT}``.
1361 #
1362 # .. _${PROJECT_NAME}_GIT_REPOSITORY_REMOTE:
1363 #
1364 # ``${PROJECT_NAME}_GIT_REPOSITORY_REMOTE=<remote-name>``
1365 #
1366 # The git remote name given to the cloned repo. This is needed for robust
1367 # git operations as described below (Default 'origin'). If a repo is
1368 # already cloned, then a remote in the already existing repo must exist
1369 # with this name or
1370 #
1371 # .. _${PROJECT_NAME}_BRANCH:
1372 #
1373 # ``${PROJECT_NAME}_BRANCH=<branch>``
1374 #
1375 # The branch of the base repo to explicitly checkout after clone (and on
1376 # each update). The value of empty "" is allowed which results in the
1377 # default branch being checked out on clone (and the ``-b <branch>``
1378 # argument to be omitted from the ``git clone`` command). The default
1379 # value determined by the variable
1380 # ``${${PROJECT_NAME}_REPOSITORY_BRANCH}}``. The default value for
1381 # ``${PROJECT_NAME}_REPOSITORY_BRANCH`` is empty.
1382 #
1383 # If the base repo already exists, no initial clone is performed and it is
1384 # assumed that it is in a state to allow it to be updated as described below.
1385 #
1386 # After the base repo is cloned, any missing extra git repositories are cloned
1387 # using CMake/CTest code in this ``tribits_ctest_driver()`` function (raw
1388 # CTest does not support cloning a list of extra repos) using the command::
1389 #
1390 # git clone [-b ${${PROJECT_NAME}_EXTRAREPO_BRANCH}] \
1391 # -o ${${PROJECT_NAME}_GIT_REPOSITORY_REMOTE} \
1392 # <extrarepo_url>
1393 #
1394 # where:
1395 #
1396 # .. _${PROJECT_NAME}_EXTRAREPOS_BRANCH:
1397 #
1398 # ``${PROJECT_NAME}_EXTRAREPOS_BRANCH=<extrarepo-branch>``
1399 #
1400 # The branch ``<extrarepo-branch>`` that each extra VC repo that is
1401 # checked out. The default value is set to ``${${PROJECT_NAME}_BRANCH}``.
1402 # If empty "", then the ``-b <branch>`` argument is omitted from the ``git
1403 # clone`` command. (NOTE: Checking out a separate branch on the extra
1404 # repos from the base repo was needed for backward compatibility for the
1405 # Trilinos project and is not recommended usage as it violates the "single
1406 # branch" approach for using `gitdist`_.)
1407 #
1408 # ``<extrarepo_url>``
1409 #
1410 # The git repo remote URL given in the file
1411 # `${PROJECT_NAME}_EXTRAREPOS_FILE`_.
1412 #
1413 # When ``CTEST_DO_UPDATES=TRUE`` (after a possible initial clone), the
1414 # function ``ctest_update()`` is called to update the base git repo. The base
1415 # git repo is updated with the custom git commands executed inside of the
1416 # ``ctest_update()`` using::
1417 #
1418 # $ git fetch ${${PROJECT_NAME}_GIT_REPOSITORY_REMOTE}
1419 # $ git clean -fdx # Remove untracked ignored files
1420 # $ git reset --hard HEAD # Clean files and set ORIG_HEAD to HEAD
1421 # $ git checkout -B ${${PROJECT_NAME}_BRANCH} \
1422 # --track origin/${${PROJECT_NAME}_BRANCH} # Sets HEAD
1423 #
1424 # The above set of commands are the maximally robust way to update a git repo.
1425 # They will correct any local state of the local repo and will put the local
1426 # repo on the requested local tracking branch. It can handled hard-reset
1427 # remote branches, previous tracking branch now missing, etc. The only
1428 # requirement is that the remote repo pointed to at
1429 # ``${${PROJECT_NAME}_GIT_REPOSITORY_REMOTE}`` is valid and has not changed
1430 # since the repo was first cloned. (NOTE: A future version of TriBITS may
1431 # automate the update of this git remote.)
1432 #
1433 # If ``${PROJECT_NAME}_BRANCH`` is empty "", the last ``git checkout -B
1434 # <branch> ...`` command is replaced with the git command::
1435 #
1436 # $ git reset --hard @{u} # Sets HEAD
1437 #
1438 # After the base git repo is updated inside of ``ctest_update()`` as described
1439 # above, each of the extra repos is updated using a similar set of git
1440 # commands::
1441 #
1442 # $ git fetch ${${PROJECT_NAME}_GIT_REPOSITORY_REMOTE}
1443 # $ git clean -fdx # Remove untracked ignored files
1444 # $ git reset --hard HEAD # Clean files and set ORIG_HEAD to HEAD
1445 # $ git checkout -B ${${PROJECT_NAME}_EXTRAREPO_BRANCH} \
1446 # --track origin/${${PROJECT_NAME}_EXTRAREPO_BRANCH} # Sets HEAD
1447 #
1448 # where if ``${PROJECT_NAME}_EXTRAREPO_BRANCH`` is empty, the last ``git
1449 # checkout -B <branch> ...`` command replaced with::
1450 #
1451 # $ git reset --hard @{u}
1452 #
1453 # **WARNING:** This version of the ``git checkout -B <branch> ...`` command
1454 # is not supported in older versions of git. Therefore, a newer version of
1455 # git is required when using named branches.
1456 #
1457 # The command ``git clone -fdx`` removes any untracked ignored files that may
1458 # have been created since the last update (either by the build process or by
1459 # someone messing around in that local git repository). The command ``git
1460 # reset --hard HEAD`` removes any untracked non-ignored files, any modified
1461 # tracked files, and sets ``ORIG_HEAD`` to the current ``HEAD``. This sets
1462 # ``ORIG_HEAD`` after the initial clone (which is needed since ``ORIG_HEAD``
1463 # is not set after the initial ``git clone`` command). This allows using the
1464 # range ``ORIG_HEAD..HEAD`` with ``git diff`` and ``git log`` commands even
1465 # after the initial clone. (Directly after the initial clone, the range
1466 # ``ORIG_HEAD..HEAD`` will be empty). The git commands ``git checkout -B
1467 # <branch> <remote>/<branch>`` or ``git reset --hard @{u}`` are used to update
1468 # the local repo to match the remote tracking branch. This is done to deal
1469 # with a possible forced push of the remote tracking branch or even changing
1470 # to different tracking branch (when using an explicit ``<branch>`` name).
1471 #
1472 # Note that the repository updating approach described above using non-empty
1473 # ``${PROJECT_NAME}_BRANCH`` is more robust, because it can recover from a
1474 # state where someone may have put a repo on a detached head or checked out a
1475 # different branch. One of these repos might get into this state when a
1476 # person is messing around in the Nightly build and source directories to try
1477 # to figure out what happened and forgot to put the repos back on the correct
1478 # tracking branch. Therefore, it is recommended to always set an explicit
1479 # ``${PROJECT_NAME}_BRANCH`` to a non-null value like ``master`` or
1480 # ``develop`` for the git repos, even if this branch is the default repo
1481 # branch.
1482 #
1483 # .. _Other CTest Driver options (tribits_ctest_driver()):
1484 #
1485 # **Other CTest Driver options (tribits_ctest_driver()):**
1486 #
1487 # Other miscellaneous vars that can be set in the CTest -S script or as env
1488 # vars are given below.
1489 #
1490 # .. _CTEST_CMAKE_GENERATOR:
1491 #
1492 # ``CTEST_CMAKE_GENERATOR="[Unix Makefiles|Ninja|..]"``
1493 #
1494 # Built-in CTest variable that determines the CMake generator used in the
1495 # inner configure. If an existing ``CMakeCache.txt`` file exists, then
1496 # the default value for the generator will be read out of that file.
1497 # Otherwise, the default generator is selected to be ``Unix Makefiles``.
1498 # Another popular option is ``Ninja``. The value of this variable
1499 # determines the type of generator used in the inner CMake configure done
1500 # by the command ``ctest_configure(...)`` called in this function. This
1501 # is done implicitly by CTest. The selected generator has an impact on
1502 # what flags can be used in `CTEST_BUILD_FLAGS`_ since ``make`` and
1503 # ``ninja`` accept different arguments in some cases.
1504 #
1505 # ``${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE=[TRUE|FALSE]``
1506 #
1507 # Puts TriBITS configure into development mode (vs. release mode) in the
1508 # outer CTest -S script. The default is provided by
1509 # ``${${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT}}`` (which is
1510 # typically set in the `<projectDir>/Version.cmake`_ file). See
1511 # `<Project>_ENABLE_DEVELOPMENT_MODE`_.
1512 #
1513 # ``${PROJECT_NAME}_VERBOSE_CONFIGURE=[TRUE|FALSE]``
1514 #
1515 # Make TriBITS run in verbose mode. (Useful for debugging hard problems.)
1516 # See `<Project>_VERBOSE_CONFIGURE`_.
1517 #
1518 # ``CTEST_CONFIGURATION_UNIT_TESTING=[TRUE|FALSE]``
1519 #
1520 # If set to ``TRUE``, then ``tribits_ctest_driver()`` is put in unit
1521 # testing mode and does not actually drive configure, build, test, and
1522 # submit. This is used to drive automated testing of the code in
1523 # ``tribits_ctest_driver()``.
1524 #
1525 # .. _Return value (tribits_ctest_driver()):
1526 #
1527 # **Return value (tribits_ctest_driver()):**
1528 #
1529 # Currently, the ctest -S script will return 0 if all of the requested
1530 # operations completed without failure. That is, the update, configure,
1531 # build, tests, coverage, dynamic analysis and submits must pass with no CMake
1532 # errors in order for a 0 return code to be returned. Therefore, the return
1533 # code from the ctest -S script can be used to drive other automated processes
1534 # that require all passing builds and tests.
1535 #
1536 # ToDo: Add another mode that will return 0 if no errors are reported in the
1537 # ctest -S driver script but ignore configure, build, and test failures that
1538 # are submitted to a CDash site (and therefore will be reported there).
1539 #
1540 function(tribits_ctest_driver)
1541
1542 message("")
1543 message("******************************")
1544 message("*** tribits_ctest_driver() ***")
1545 message("******************************")
1546 message("")
1547
1548 initialize_error_queue()
1549
1550 # The name of the source directory. Defaults to project name, but
1551 # can be overridden by the environment for cases in which the source
1552 # directory name does not match the project name.
1553 set_default_and_from_env(CTEST_SOURCE_NAME ${PROJECT_NAME})
1554
1555 message(
1556 "\n***"
1557 "\n*** Setting input options to default and reading from env ..."
1558 "\n***\n")
1559
1560 set_default_and_from_env( CTEST_CONFIGURATION_UNIT_TESTING OFF )
1561
1562 # The type of test (e.g. Nightly, Experimental, Continuous)
1563 set_default_and_from_env( CTEST_TEST_TYPE Experimental )
1564
1565 # The default track to send the build to. This can be changed to send
1566 # the data to a different nightly grouping on the dashboard.
1567 # If the test type is set to Experimental though the track is forced
1568 # to "Experimental" this is so that we can have experimental tests
1569 # on branches.
1570 if(${PROJECT_NAME}_TESTING_TRACK)
1571 set(${PROJECT_NAME}_TRACK_DEFAULT ${${PROJECT_NAME}_TESTING_TRACK})
1572 else()
1573 set(${PROJECT_NAME}_TRACK_DEFAULT "")
1574 endif()
1575 print_var(${PROJECT_NAME}_TRACK_DEFAULT)
1576 set_default_and_from_env(${PROJECT_NAME}_TRACK "${${PROJECT_NAME}_TRACK_DEFAULT}")
1577 if(CTEST_TEST_TYPE STREQUAL "Experimental" OR CTEST_TEST_TYPE STREQUAL "EXPERIMENTAL")
1578 set(${PROJECT_NAME}_TRACK "Experimental")
1579 message("-- Test type is Experimental. Forcing ${PROJECT_NAME}_TRACK to Experimental")
1580 print_var(${PROJECT_NAME}_TRACK)
1581 endif()
1582
1583 # The name of the site in the dashboard (almost never need to override this)
1584 set_default_and_from_env( CTEST_SITE ${CTEST_SITE_DEFAULT} )
1585
1586 # The root of the dashboard where ${PROJECT_NAME} will be cloned and the
1587 # BUILD directory will be create (only override for separate testing)
1588 set_default_and_from_env( CTEST_DASHBOARD_ROOT "" )
1589 if (CTEST_DASHBOARD_ROOT STREQUAL "PWD")
1590 set(CTEST_DASHBOARD_ROOT ${CMAKE_CURRENT_BINARY_DIR})
1591 print_var(CTEST_DASHBOARD_ROOT)
1592 endif()
1593
1594 # Verobse configure or now
1595 set_default_and_from_env( ${PROJECT_NAME}_VERBOSE_CONFIGURE OFF )
1596
1597 # Set the default compiler version
1598 set_default_and_from_env(COMPILER_VERSION UNKNOWN)
1599
1600 # The name of the build that appears in the dashboard
1601 set_default_and_from_env( CTEST_BUILD_NAME
1602 "${HOST_TYPE}-${COMPILER_VERSION}-${BUILD_DIR_NAME}" )
1603
1604 # Remove the entire build directory if it exists or not
1605 set_default_and_from_env( CTEST_START_WITH_EMPTY_BINARY_DIRECTORY TRUE )
1606
1607 # Call ctest_start(...) to start a new CDash build case or not
1608 set_default_and_from_env( CTEST_DO_NEW_START TRUE )
1609
1610 # Remove an existing CMakeCache.txt file or not
1611 set_default_and_from_env( CTEST_WIPE_CACHE TRUE )
1612
1613 # Extra notes files suggested by user
1614 set_default_and_from_env( CTEST_NOTES_FILES "" )
1615 set(CTEST_NOTES_FILES_INPUT_BY_USER "${CTEST_NOTES_FILES}")
1616
1617 # Select a default generator.
1618 select_default_generator()
1619 set_default_and_from_env( CTEST_CMAKE_GENERATOR ${DEFAULT_GENERATOR})
1620
1621 # Do the Git updates or not
1622 set_default_and_from_env( CTEST_DO_UPDATES TRUE )
1623
1624 # Generate the XML dependency output files or not in the inner CMake
1625 # configure. There is really no reason to do this. This option is
1626 # maintained for backward compatibility.
1627 set_default_and_from_env( CTEST_GENERATE_DEPS_XML_OUTPUT_FILE FALSE )
1628
1629 # Flags used on git when doing a Git update
1630 set_default_and_from_env( CTEST_UPDATE_ARGS "")
1631
1632 # Flags used on update when doing a Git update
1633 set_default_and_from_env( CTEST_UPDATE_OPTIONS "")
1634
1635 # Do an update only to show the version
1636 set_default_and_from_env( CTEST_UPDATE_VERSION_ONLY FALSE )
1637
1638 # Set the GitHub PR or GitLab MR ID (will provide link in CDash back to the
1639 # GitHub PR or GitLab MR)
1640 set_default_and_from_env( CTEST_CHANGE_ID "" )
1641
1642 # Do all-at-once configure, build, test and submit (or package-by-package)
1643 if ("${${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE_DEFAULT}" STREQUAL "")
1644 set(${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE_DEFAULT FALSE)
1645 endif()
1646 set_default_and_from_env( ${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE
1647 ${${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE_DEFAULT} )
1648
1649 # Extra inner CMake configure options that override everything
1650 set_default_and_from_env(${PROJECT_NAME}_EXTRA_CONFIGURE_OPTIONS "")
1651
1652 # Call ctest_configure(...) or not
1653 set_default_and_from_env( CTEST_DO_CONFIGURE TRUE )
1654
1655 # Flags passed to 'make'
1656 if("${CTEST_CMAKE_GENERATOR}" MATCHES "Unix Makefiles")
1657 set_default_and_from_env( CTEST_BUILD_FLAGS "-j2")
1658 else()
1659 set_default_and_from_env( CTEST_BUILD_FLAGS "")
1660 endif()
1661
1662 # Generate version date files or not
1663 set_default_and_from_env(${PROJECT_NAME}_GENERATE_VERSION_DATE_FILES "")
1664
1665 # Call ctest_build(...) or not
1666 set_default_and_from_env( CTEST_DO_BUILD TRUE )
1667
1668 # Call ctest_build( ... install ... ) or not
1669 set_default_and_from_env( CTEST_DO_INSTALL FALSE )
1670
1671 # Do the tests or not (Note: must be true for coverage testing)
1672 set_default_and_from_env( CTEST_DO_TEST TRUE )
1673
1674 # Pass through
1675 set_default_and_from_env( ${PROJECT_NAME}_INNER_ENABLE_TESTS ON )
1676
1677 # Pass through
1678 set_default_and_from_env( ${PROJECT_NAME}_SKIP_CTEST_ADD_TEST FALSE )
1679
1680 # Maximum number of procs an mpi test can request (if more are requested,
1681 # the test will be skipped). Value of 0 means no override (determined
1682 # internally).
1683 set_default_and_from_env( MPI_EXEC_MAX_NUMPROCS 0 )
1684
1685 # How many tests ctest will spawn simultaneously
1686 set_default_and_from_env( CTEST_PARALLEL_LEVEL 1 )
1687
1688 # Turn off or change warnings-as-errors flag(s) (i.e. -Werror)
1689 set_default_and_from_env( ${PROJECT_NAME}_WARNINGS_AS_ERRORS_FLAGS "" )
1690
1691 # Do coverage testing or not
1692 set_default_and_from_env( CTEST_DO_COVERAGE_TESTING OFF )
1693
1694 # Command to run to get coverage results
1695 set_default_and_from_env( CTEST_COVERAGE_COMMAND gcov )
1696
1697 # Do memory testing (i.e. valgrind) or not
1698 set_default_and_from_env( CTEST_DO_MEMORY_TESTING FALSE )
1699
1700 # Command used to perform the memory testing (i.e. valgrind)
1701 find_program(VALGRIND_EXE NAMES valgrind)
1702 print_var(VALGRIND_EXE)
1703 if (VALGRIND_EXE)
1704 set(CTEST_MEMORYCHECK_COMMAND_DEFAULT "${VALGRIND_EXE}")
1705 else()
1706 set(CTEST_MEMORYCHECK_COMMAND_DEFAULT)
1707 endif()
1708 set_default_and_from_env( CTEST_MEMORYCHECK_COMMAND "${CTEST_MEMORYCHECK_COMMAND_DEFAULT}" )
1709
1710 # Set the default options
1711 set_default_and_from_env( CTEST_MEMORYCHECK_COMMAND_OPTIONS "")
1712
1713 # Generate the basic package dependencies XML file in the outer CTest
1714 # program. This XML file is used to match up modified files with changed
1715 # TriBITS packages. This file only needs to be generated in CI iterations
1716 # and is not needed in Nightly testing. Turning off its generation can also
1717 # speed up local manual testing for large projects with lots of TriBITS
1718 # packages.
1719 set_default_and_from_env( CTEST_GENERATE_OUTER_DEPS_XML_OUTPUT_FILE TRUE )
1720
1721 # Generate and submit the CDash subprojects XML file
1722 set_default_and_from_env( CTEST_SUBMIT_CDASH_SUBPROJECTS_DEPS_FILE TRUE )
1723
1724 # Submit the results to the dashboard or not
1725 set_default_and_from_env( CTEST_DO_SUBMIT TRUE )
1726
1727 # Control the number of submit retries and the delay
1728 set_default_and_from_env( CTEST_SUBMIT_RETRY_COUNT 5 ) # Default defined by ctest
1729 set_default_and_from_env( CTEST_SUBMIT_RETRY_DELAY 3 ) # Default defined by ctest?
1730
1731 if ("${${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE_DEFAULT}" STREQUAL "")
1732 set(${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE_DEFAULT OFF)
1733 endif()
1734 set_default_and_from_env( ${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE
1735 ${${PROJECT_NAME}_ENABLE_SECONDARY_TESTED_CODE_DEFAULT} )
1736
1737 # List of additional packages that will be enabled over the current set of
1738 # all packages (that would be set by ${PROJECT_NAME}_ENABLE_ALL_PACKAGES).
1739 set_default_and_from_env( ${PROJECT_NAME}_ADDITIONAL_PACKAGES "" )
1740
1741 # List of packages to not directly process. .
1742 set_default_and_from_env( ${PROJECT_NAME}_EXCLUDE_PACKAGES "" )
1743 string(REPLACE "," ";" ${PROJECT_NAME}_EXCLUDE_PACKAGES
1744 "${${PROJECT_NAME}_EXCLUDE_PACKAGES}" )
1745
1746 if(CTEST_TEST_TYPE STREQUAL "Nightly")
1747 set_default_and_from_env(${PROJECT_NAME}_REPOSITORY_LOCATION
1748 "${${PROJECT_NAME}_REPOSITORY_LOCATION_NIGHTLY_DEFAULT}")
1749 else()
1750 set_default_and_from_env(${PROJECT_NAME}_REPOSITORY_LOCATION
1751 "${${PROJECT_NAME}_REPOSITORY_LOCATION_DEFAULT}")
1752 endif()
1753
1754 set_default_and_from_env( ${PROJECT_NAME}_GIT_REPOSITORY_REMOTE "origin" )
1755
1756 if(${PROJECT_NAME}_REPOSITORY_BRANCH)
1757 set(${PROJECT_NAME}_BRANCH_DEFAULT ${${PROJECT_NAME}_REPOSITORY_BRANCH})
1758 else()
1759 set(${PROJECT_NAME}_BRANCH_DEFAULT "")
1760 endif()
1761 set_default_and_from_env( ${PROJECT_NAME}_BRANCH "${${PROJECT_NAME}_BRANCH_DEFAULT}" )
1762
1763 set_default_and_from_env( ${PROJECT_NAME}_EXTRAREPOS_BRANCH "${${PROJECT_NAME}_BRANCH}" )
1764
1765 set_default_and_from_env( ${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE "${${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT}" )
1766
1767 # Select the ${PROJECT_NAME} packages to enable (empty means to select all
1768 # available). This will override any disabled packages but not those
1769 # disabled by ${PROJECT_NAME}_EXCLUDE_PACKAGES.
1770 set_default_and_from_env( ${PROJECT_NAME}_PACKAGES "" )
1771
1772 # Also allow the package enables to be set in a CMake fragment file
1773 set_default_and_from_env( ${PROJECT_NAME}_PACKAGE_ENABLES_FILE "" )
1774
1775 if (
1776 (NOT "${${PROJECT_NAME}_PACKAGES}" STREQUAL "")
1777 AND
1778 (NOT "${${PROJECT_NAME}_PACKAGE_ENABLES_FILE}" STREQUAL "")
1779 )
1780 message(FATAL_ERROR "ERROR: Both"
1781 " ${PROJECT_NAME}_PACKAGES and ${PROJECT_NAME}_PACKAGE_ENABLES_FILE"
1782 " cannot be non-empty! Set one or the other to select the set of"
1783 " packages to be processed/tested.")
1784 endif()
1785
1786 set(${PROJECT_NAME}_PACKAGES_USER_SELECTED ${${PROJECT_NAME}_PACKAGES})
1787 split("${${PROJECT_NAME}_PACKAGES_USER_SELECTED}" ","
1788 ${PROJECT_NAME}_PACKAGES_USER_SELECTED)
1789 set(${PROJECT_NAME}_PACKAGES "")
1790 # Note: above, we have to keep the name ${PROJECT_NAME}_PACKAGES to maintain
1791 # backward compatibility of this CTest script but we want to let
1792 # ${PROJECT_NAME}_PACKAGES always be the full set of packages as defined by
1793 # the basic readin process.
1794
1795
1796 # Set the file that the extra repos will be read from
1797 #
1798 # NOTE: Here, we have no choice but to point into the "driver"
1799 # ${PROJECT_NAME} source tree because the local ${PROJECT_NAME} sources have
1800 # not even been checked out yet! Unless, of course, we are unit testing in
1801 # which case we will use whatever has been passed in.
1802
1803 if (${PROJECT_NAME}_SKIP_EXTRAREPOS_FILE)
1804 set(${PROJECT_NAME}_EXTRAREPOS_FILE_DEFAULT)
1805 else()
1806 set(${PROJECT_NAME}_EXTRAREPOS_FILE_DEFAULT
1807 "${TRIBITS_PROJECT_ROOT}/cmake/${${PROJECT_NAME}_EXTRA_EXTERNAL_REPOS_FILE_NAME}")
1808 endif()
1809 set_default_and_from_env(${PROJECT_NAME}_EXTRAREPOS_FILE
1810 "${${PROJECT_NAME}_EXTRAREPOS_FILE_DEFAULT}")
1811
1812 # Select the set of extra external repos to add in packages.
1813 # These are the same types as CTEST_TEST_TYPE (e.g. 'Continuous' and
1814 # 'Nightly'). This is set by default to ${CTEST_TEST_TYPE} can be
1815 # overridden independent of ${CTEST_TEST_TYPE} also.
1816 #
1817 # If in release mode generally we do not want any external repositories
1818 # even though the CTEST_TEST_TYPE is set to "Nightly" for most release
1819 # builds.
1820 assert_defined(${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE)
1821 if(${PROJECT_NAME}_ENABLE_DEVELOPMENT_MODE)
1822 set(${PROJECT_NAME}_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE_DEFAULT ${CTEST_TEST_TYPE})
1823 else()
1824 set(${PROJECT_NAME}_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE_DEFAULT "None")
1825 endif()
1826 set_default_and_from_env( ${PROJECT_NAME}_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE
1827 "${${PROJECT_NAME}_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE_DEFAULT}" )
1828
1829 set_default_and_from_env(${PROJECT_NAME}_PRE_REPOSITORIES "")
1830 split("${${PROJECT_NAME}_PRE_REPOSITORIES}" "," ${PROJECT_NAME}_PRE_REPOSITORIES)
1831
1832 set_default_and_from_env(${PROJECT_NAME}_EXTRA_REPOSITORIES "")
1833 split("${${PROJECT_NAME}_EXTRA_REPOSITORIES}" "," ${PROJECT_NAME}_EXTRA_REPOSITORIES)
1834
1835 # Set as part of CI testing in order to only enable modified packages
1836 set_default_and_from_env( CTEST_ENABLE_MODIFIED_PACKAGES_ONLY OFF )
1837
1838 # Set if implicitly enabled packages should be explicitly processed in
1839 # package-by-package mode.
1840 if (CTEST_ENABLE_MODIFIED_PACKAGES_ONLY AND NOT CTEST_START_WITH_EMPTY_BINARY_DIRECTORY)
1841 set( CTEST_EXPLICITLY_ENABLE_IMPLICITLY_ENABLED_PACKAGES_DEFAULT FALSE )
1842 else()
1843 set( CTEST_EXPLICITLY_ENABLE_IMPLICITLY_ENABLED_PACKAGES_DEFAULT TRUE )
1844 endif()
1845 set_default_and_from_env( CTEST_EXPLICITLY_ENABLE_IMPLICITLY_ENABLED_PACKAGES
1846 ${CTEST_EXPLICITLY_ENABLE_IMPLICITLY_ENABLED_PACKAGES_DEFAULT})
1847
1848 if (CTEST_ENABLE_MODIFIED_PACKAGES_ONLY)
1849 set(${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES_DEFAULT TRUE)
1850 else()
1851 set(${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES_DEFAULT FALSE)
1852 endif()
1853 set_default_and_from_env( ${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES
1854 ${${PROJECT_NAME}_ENABLE_ALL_FORWARD_DEP_PACKAGES_DEFAULT})
1855
1856 # Set if we should disable enabled fwd packages based on disabled required deps.
1857 # To make testing robust, we need to do this.
1858 if ("${${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES_DEFAULT}" STREQUAL "")
1859 set(${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES_DEFAULT ON)
1860 endif()
1861 set_default_and_from_env(${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES
1862 ${${PROJECT_NAME}_DISABLE_ENABLED_FORWARD_DEP_PACKAGES_DEFAULT})
1863
1864 # Set second drop site and location
1865 set_default_and_from_env( TRIBITS_2ND_CTEST_DROP_SITE "" )
1866 set_default_and_from_env( TRIBITS_2ND_CTEST_DROP_LOCATION "" )
1867
1868 message(
1869 "\n***"
1870 "\n*** Setting unit testing input options to default and reading from env ..."
1871 "\n***\n")
1872
1873 set_default_and_from_env( CTEST_DEPENDENCY_HANDLING_UNIT_TESTING FALSE )
1874
1875 set_default_and_from_env( CTEST_UPDATE_UNIT_TESTING_MODE
1876 ${CTEST_DEPENDENCY_HANDLING_UNIT_TESTING} )
1877
1878 set_default_and_from_env( CTEST_UPDATE_RETURN_VAL 0 )
1879
1880 if (CTEST_DEPENDENCY_HANDLING_UNIT_TESTING)
1881 set(GIT_EXECUTABLE /somebasedir/git)
1882 endif()
1883
1884
1885 message(
1886 "\n***"
1887 "\n*** Misc setup ..."
1888 "\n***\n")
1889
1890 #
1891 # Setup and create the base dashboard directory if it is not created yet.
1892 #
1893
1894 # NOTE: This is only used in general testing dashboard mode, not in local
1895 # experimental testing mode.
1896
1897 if (CTEST_DASHBOARD_ROOT)
1898 set( CTEST_BINARY_NAME BUILD )
1899 set( CTEST_SOURCE_DIRECTORY "${CTEST_DASHBOARD_ROOT}/${CTEST_SOURCE_NAME}")
1900 set( CTEST_BINARY_DIRECTORY "${CTEST_DASHBOARD_ROOT}/${CTEST_BINARY_NAME}")
1901 if (NOT EXISTS "${CTEST_DASHBOARD_ROOT}")
1902 message("Creating the dashboard root directory \"${CTEST_DASHBOARD_ROOT}\" ...")
1903 file(MAKE_DIRECTORY "${CTEST_DASHBOARD_ROOT}")
1904 endif()
1905 endif()
1906 print_var(CTEST_SOURCE_DIRECTORY)
1907 print_var(CTEST_BINARY_DIRECTORY)
1908
1909 set(PROJECT_SOURCE_DIR "${CTEST_SOURCE_DIRECTORY}")
1910 set(PROJECT_BINARY_DIR "${CTEST_BINARY_DIRECTORY}")
1911 print_var(PROJECT_SOURCE_DIR)
1912 print_var(PROJECT_BINARY_DIR)
1913
1914 # Set override hook for unit testing
1915 set_default_and_from_env( ${PROJECT_NAME}_SOURCE_DIRECTORY ${CTEST_SOURCE_DIRECTORY} )
1916
1917 # Must be set here after CTEST_BINARY_DIRECTORY is set!
1918 set(FAILED_PACKAGES_FILE_NAME "${CTEST_BINARY_DIRECTORY}/failedPackages.txt")
1919
1920 #
1921 # Some platform-independent setup
1922 #
1923
1924 include("${TRIBITS_PROJECT_ROOT}/CTestConfig.cmake")
1925 set(CTEST_USE_LAUNCHERS 1)
1926
1927 # For coverage dashboards, send results to specialized dashboard if
1928 # requested
1929 if (CTEST_DO_COVERAGE_TESTING)
1930 # Allow override of CDash drop site but use standard by default
1931 set_default(CTEST_DROP_SITE_COVERAGE_DEFAULT
1932 ${CTEST_DROP_SITE})
1933 set_default_and_from_env(CTEST_DROP_SITE_COVERAGE
1934 "${CTEST_DROP_SITE_COVERAGE_DEFAULT}")
1935 set(CTEST_DROP_SITE "${CTEST_DROP_SITE_COVERAGE}" )
1936 # Allow override of CDash drop location but use standard by default
1937 set_default(CTEST_DROP_LOCATION_COVERAGE_DEFAULT
1938 ${CTEST_DROP_LOCATION})
1939 set_default_and_from_env(CTEST_DROP_LOCATION_COVERAGE
1940 "${CTEST_DROP_LOCATION_COVERAGE_DEFAULT}")
1941 set(CTEST_DROP_LOCATION "${CTEST_DROP_LOCATION_COVERAGE}" )
1942
1943 # NOTE: You must set these down below the include of
1944 # CTestConfig.cmake so that CTEST_DROP_SITE and CTEST_DROP_LOCATION read
1945 # from that file will set the defaults for the coverage options.
1946
1947 endif()
1948
1949 #
1950 # Setup for the VC update
1951 #
1952
1953 set(CREATE_VC_UPDATE_FILE FALSE)
1954
1955 set(CTEST_UPDATE_COMMANDS_OUTPUT_FILE
1956 "${CTEST_BINARY_DIRECTORY}/UpdateCommandsOutput.txt")
1957
1958 if (CTEST_DO_UPDATES)
1959
1960 set(UPDATE_TYPE "git")
1961 message("UPDATE_TYPE = '${UPDATE_TYPE}'")
1962
1963 #
1964 # Set the initial clone command for if the local repo is missing
1965 #
1966
1967 if (${PROJECT_NAME}_BRANCH)
1968 set(CHECKOUT_BRANCH_ARG "-b ${${PROJECT_NAME}_BRANCH} ")
1969 else()
1970 set(CHECKOUT_BRANCH_ARG)
1971 endif()
1972
1973 set( _CTEST_CHECKOUT_COMMAND
1974 "\"${GIT_EXECUTABLE}\" clone ${CHECKOUT_BRANCH_ARG}-o ${${PROJECT_NAME}_GIT_REPOSITORY_REMOTE} ${CTEST_UPDATE_ARGS} ${${PROJECT_NAME}_REPOSITORY_LOCATION}" )
1975 message("CTEST_CHECKOUT_COMMAND=${_CTEST_CHECKOUT_COMMAND}")
1976
1977 if(NOT EXISTS "${CTEST_SOURCE_DIRECTORY}")
1978 message("${CTEST_SOURCE_DIRECTORY} does not exist so setting up for an initial checkout")
1979 set( CTEST_CHECKOUT_COMMAND "${_CTEST_CHECKOUT_COMMAND}")
1980 # NOTE: Just to be safe, only set CTEST_CHECKOUT_COMMAND to do a clone
1981 # if the repo does not already exist!
1982 else()
1983 message("${CTEST_SOURCE_DIRECTORY} exists so skipping the initial checkout.")
1984 if (NOT CTEST_UPDATE_VERSION_ONLY)
1985 set(CREATE_VC_UPDATE_FILE TRUE)
1986 endif()
1987 endif()
1988
1989 #
1990 # Set the git update command for an already cloned repo
1991 #
1992
1993 # CTest always needs the raw git command in order to do stuff like get the
1994 # version of the repo before and after the update, even if you provide a
1995 # custom update command.
1996 set(CTEST_GIT_COMMAND "${GIT_EXECUTABLE}")
1997 message("CTEST_GIT_COMMAND=${CTEST_GIT_COMMAND}")
1998 # NOTE: You can't put the above command "${GIT_EXECUTABLE}" in quotes like
1999 # "'${GIT_EXECUTABLE}'" or "\"${GIT_EXECUTABLE}\"" or it will not work and
2000 # ctest_update() will return failed!
2001
2002 if (NOT CTEST_UPDATE_VERSION_ONLY)
2003 # Provide a custom command to do the update
2004 set(CTEST_GIT_UPDATE_CUSTOM
2005 "${CMAKE_COMMAND}"
2006 -DGIT_EXE=${GIT_EXECUTABLE}
2007 -DREMOTE_NAME=${${PROJECT_NAME}_GIT_REPOSITORY_REMOTE}
2008 -DBRANCH=${${PROJECT_NAME}_BRANCH}
2009 -DUNIT_TEST_MODE=${CTEST_DEPENDENCY_HANDLING_UNIT_TESTING}
2010 -DOUTPUT_FILE=${CTEST_UPDATE_COMMANDS_OUTPUT_FILE}
2011 -P ${THIS_CMAKE_CURRENT_LIST_DIR}/tribits_ctest_update_commands_wrapper.cmake
2012 )
2013 message("CTEST_GIT_UPDATE_CUSTOM=${CTEST_GIT_UPDATE_CUSTOM}")
2014 else()
2015 # CTest will just report the version already checked out in
2016 # ctest_update().
2017 endif()
2018
2019 endif()
2020
2021 #
2022 # This hack is a workaround for a bug in CMake. Since we're calling
2023 # ctest_start() inside a function scope, CTEST_RUN_CURRENT_SCRIPT doesn't
2024 # get set in the root scope, and setting it manually at the root or via
2025 # PARENT_SCOPE isn't scalable since ctest_start() is nested inside several
2026 # layers of functions in some cases. So, instead, we just turn CTEST_COMMAND
2027 # into a no-op.
2028 #
2029
2030 set(CTEST_SOURCE_DIRECTORY ${CTEST_SOURCE_DIRECTORY} CACHE INTERNAL "")
2031 set(CTEST_BINARY_DIRECTORY ${CTEST_BINARY_DIRECTORY} CACHE INTERNAL "")
2032 if ("${CTEST_COMMAND}" STREQUAL "")
2033 set(CTEST_COMMAND "${CMAKE_COMMAND} -E echo")
2034 endif()
2035 set(CTEST_COMMAND ${CTEST_COMMAND} CACHE INTERNAL "")
2036
2037 #
2038 # Empty out the binary directory
2039 #
2040
2041 if (CTEST_START_WITH_EMPTY_BINARY_DIRECTORY AND NOT CTEST_DO_NEW_START)
2042 message("\nSkipping calling ctest_empty_binary_directory() even though"
2043 "CTEST_START_WITH_EMPTY_BINARY_DIRECTORY='${CTEST_START_WITH_EMPTY_BINARY_DIRECTORY}'"
2044 " because CTEST_DO_NEW_START='${CTEST_DO_NEW_START}'!"
2045 " You can't empty the binary directory unless you will be starting"
2046 " a new dashboard!")
2047 elseif (CTEST_START_WITH_EMPTY_BINARY_DIRECTORY)
2048 message("\nCleaning out binary directory '${CTEST_BINARY_DIRECTORY}' ...")
2049 ctest_empty_binary_directory("${CTEST_BINARY_DIRECTORY}")
2050 endif()
2051 # NOTE: The above command will *not* delete the build directory unless there
2052 # is a CMakeLists.txt file in this directory. I think Kitware put in this
2053 # check to avoid accidentally deleting the wrong directory by accident.
2054 # Also note that you have to delete the build directory before any commands
2055 # are run that would write files to them (and many of the steps in this
2056 # process do write files to the binary directory other than just CMake).
2057
2058 message(
2059 "\n***"
2060 "\n*** Read in the set of extra repos ..."
2061 "\n***\n")
2062
2063 tribits_setup_extrarepos()
2064
2065 # NOTE: You have to set up the set of extra repos before you can read the
2066 # Dependencies.cmake files since the extra repos must be cloned first.
2067
2068 message(
2069 "\n***"
2070 "\n*** Start up a new dashboard calling ctest_start(...) ..."
2071 "\n***\n")
2072
2073 set(CTEST_TESTING_TAG_FILE "${CTEST_BINARY_DIRECTORY}/Testing/TAG")
2074
2075 print_var(CTEST_TEST_TYPE)
2076 print_var(${PROJECT_NAME}_TRACK)
2077
2078 set(CTEST_START_ARGS ${CTEST_TEST_TYPE})
2079 if(${PROJECT_NAME}_TRACK)
2080 list(APPEND CTEST_START_ARGS TRACK ${${PROJECT_NAME}_TRACK})
2081 endif()
2082
2083 if (CTEST_DO_NEW_START)
2084
2085 message(
2086 "\n***"
2087 "\n*** Start up a new dashboard calling ctest_start(...) ..."
2088 "\n***\n")
2089
2090 # NOTE: If the source directory does not yet exist, then ctest_start()
2091 # will clone it!
2092
2093 else()
2094
2095 message(
2096 "\n***"
2097 "\n*** Use previous dashboard calling ctest_start(... APPEND) due to CTEST_DO_NEW_START='${CTEST_DO_NEW_START}' ..."
2098 "\n***\n")
2099
2100 if (EXISTS "${CTEST_TESTING_TAG_FILE}")
2101 file(READ "${CTEST_TESTING_TAG_FILE}" TAG_FILE_CONTENTS_STR)
2102 message(
2103 "\nPrevious file:"
2104 "\n"
2105 "\n '${CTEST_TESTING_TAG_FILE}'"
2106 "\n"
2107 "\nexists with contents:\n"
2108 "\n"
2109 "${TAG_FILE_CONTENTS_STR}\n")
2110 else()
2111 message(FATAL_ERROR
2112 "ERROR: Previous file '${CTEST_TESTING_TAG_FILE}' does NOT exist!"
2113 " A previous ctest_start() was not called. Please call again"
2114 " this time setting CTEST_DO_NEW_START=TRUE")
2115 endif()
2116
2117 list(APPEND CTEST_START_ARGS APPEND)
2118
2119 endif()
2120
2121 message("\nCalling ctest_start(${CTEST_START_ARGS})... \n\n")
2122 ctest_start(${CTEST_START_ARGS})
2123
2124 tribits_remember_if_configure_attempted()
2125
2126 tribits_get_cdash_results_string_and_write_to_file(
2127 CDASH_RESULTS_STRING_OUT CDASH_RESULTS_STRING
2128 CDASH_RESULTS_FILE_OUT "${CTEST_BINARY_DIRECTORY}/CDashResults.txt" )
2129 message("Results will be submitted on CDash at the following links:\n\n"
2130 "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n\n"
2131 "${CDASH_RESULTS_STRING}\n"
2132 "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n"
2133 )
2134
2135 message(
2136 "\n***"
2137 "\n*** Update the source code repositories ..."
2138 "\n***\n")
2139
2140 set(UPDATE_FAILED FALSE)
2141
2142 if (CTEST_DO_UPDATES)
2143
2144 if(NOT EXISTS "${CTEST_SOURCE_DIRECTORY}")
2145 queue_error("error: source directory does not exist just prior to CTEST_UPDATE call -- initial checkout did not work")
2146 report_queued_errors()
2147 return()
2148 endif()
2149
2150 if (EXISTS "${CTEST_UPDATE_COMMANDS_OUTPUT_FILE}")
2151 file(REMOVE "${CTEST_UPDATE_COMMANDS_OUTPUT_FILE}")
2152 endif()
2153
2154 message("\nCalling ctest_update() to update base source repo '${CTEST_SOURCE_DIRECTORY}' ...")
2155 ctest_update_wrapper( SOURCE "${CTEST_SOURCE_DIRECTORY}"
2156 RETURN_VALUE CTEST_UPDATE_RETURN_VAL)
2157 message("ctest_update(...) returned '${CTEST_UPDATE_RETURN_VAL}' [ rtn >= 0: num files; rnt == -1: error ]")
2158
2159 if ("${CTEST_UPDATE_RETURN_VAL}" STREQUAL "-1")
2160 set(UPDATE_FAILED TRUE)
2161 endif()
2162
2163 # Print the output from the git commands called in ctest_update()
2164 if (EXISTS "${CTEST_UPDATE_COMMANDS_OUTPUT_FILE}")
2165 file(READ "${CTEST_UPDATE_COMMANDS_OUTPUT_FILE}" CTEST_UPDATE_COMMANDS_OUTPUT_STR)
2166 message("\n------------------------------------------------------------------------")
2167 message("${CTEST_UPDATE_COMMANDS_OUTPUT_STR}")
2168 message("------------------------------------------------------------------------\n")
2169 endif()
2170
2171 if (NOT CTEST_UPDATE_VERSION_ONLY)
2172 tribits_clone_or_update_extra_repos(${CTEST_UPDATE_RETURN_VAL} LOC_UPDATE_FAILED)
2173 if (LOC_UPDATE_FAILED)
2174 set(UPDATE_FAILED TRUE)
2175 endif()
2176 endif()
2177
2178 if (CREATE_VC_UPDATE_FILE)
2179 tribits_create_repo_updates_file()
2180 # NOTE: We can only create the Updates.txt file using `gitdist
2181 # ... ORIG_HEAD..HEAD` when doing an update and not after the initial
2182 # clone. That is because ORIG_HEAD will not exist for the base git repo
2183 # after the initial clone.
2184 endif()
2185
2186 if (UPDATE_FAILED)
2187 message("Update FAILED!")
2188 endif()
2189
2190 else()
2191
2192 message("Skipping the update by request!")
2193
2194 endif()
2195
2196
2197 message(
2198 "\n***"
2199 "\n*** Read in the set of packages and their dependencies ..."
2200 "\n***\n")
2201
2202 # NOTE: You must read the Dependencies.cmake files *after* you have cloned
2203 # (or updated) all of the code!
2204
2205 tribits_setup_packages()
2206
2207 set(CDASH_SUBPROJECT_XML_FILE
2208 "${CTEST_BINARY_DIRECTORY}/${${PROJECT_NAME}_CDASH_SUBPROJECT_DEPS_XML_FILE_NAME}")
2209 print_var(CDASH_SUBPROJECT_XML_FILE)
2210
2211 message(
2212 "\n***"
2213 "\n*** Disabling packages based on what was set in ${PROJECT_NAME}_EXCLUDE_PACKAGES ..."
2214 "\n***\n")
2215
2216 disable_excluded_packages()
2217
2218 if (NOT CTEST_ENABLE_MODIFIED_PACKAGES_ONLY)
2219 message(
2220 "\n***"
2221 "\n*** Determining what packages to enable based what was set in ${PROJECT_NAME}_PACKAGES by the user ..."
2222 "\n***\n")
2223 enable_user_selected_packages()
2224 else()
2225 message(
2226 "\n***"
2227 "\n*** Determining what packages to enable based on what changed (and failed last CI iteration) ..."
2228 "\n***\n")
2229 enable_only_modified_packages()
2230 endif()
2231
2232 message(
2233 "\n***"
2234 "\n*** Adjust the package dependencies to enable upstream and"
2235 " (optionally) downstream packages ..."
2236 "\n***"
2237 )
2238
2239 set(${PROJECT_NAME}_ENABLE_TESTS ON)
2240 set(${PROJECT_NAME}_ENABLE_EXAMPLES ON)
2241 set(${PROJECT_NAME}_ENABLE_ALL_OPTIONAL_PACKAGES ON)
2242 set(DO_PROCESS_MPI_ENABLES FALSE) # Should not be needed but CMake is messing up
2243 tribits_adjust_and_print_package_dependencies()
2244 # Above sets ${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES
2245
2246 select_final_set_of_packages_to_directly_test()
2247 # Above sets ${PROJECT_NAME}_PACKAGES_TO_DIRECTLY_TEST
2248
2249 tribits_print_packages_list_enable_status_from_var(
2250 ${PROJECT_NAME}_PACKAGES_TO_DIRECTLY_TEST
2251 "\nFinal set of packages to be explicitly processed by CTest/CDash" "" ON NONEMPTY)
2252
2253 message(
2254 "\n***"
2255 "\n*** Determine if to go ahead with configure, build, test ..."
2256 "\n***")
2257
2258 if (CTEST_ENABLE_MODIFIED_PACKAGES_ONLY
2259 AND ${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES GREATER 0
2260 AND MODIFIED_PACKAGES_LIST
2261 )
2262 message("\nMODIFIED_PACKAGES_LIST='${MODIFIED_PACKAGES_LIST}'"
2263 ": Found modified packages, processing enabled packages!\n")
2264 else()
2265 message(
2266 "\nCTEST_ENABLE_MODIFIED_PACKAGES_ONLY=${CTEST_ENABLE_MODIFIED_PACKAGES_ONLY}"
2267 " Running in regular mode, processing all enabled packages!\n")
2268 endif()
2269
2270 if (${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES GREATER 0)
2271 message(
2272 "\n${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES=${${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES}:"
2273 " Configuring packages!\n")
2274 else()
2275 message(
2276 "\n${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES=${${PROJECT_NAME}_NUM_ENABLED_INTERNAL_TOPLEVEL_PACKAGES}:"
2277 " Exiting the script!\n")
2278 report_queued_errors()
2279 return()
2280 endif()
2281
2282 #
2283 # Delete the CMakeCache.txt file and the CMakeFiles directory for a clean
2284 # reconfigure.
2285 #
2286
2287 if (CTEST_DO_CONFIGURE AND CTEST_WIPE_CACHE)
2288 set(CACHE_FILE_NAME "${CTEST_BINARY_DIRECTORY}/CMakeCache.txt")
2289 if (EXISTS "${CACHE_FILE_NAME}")
2290 message("Removing existing cache file '${CACHE_FILE_NAME}' ...")
2291 file(REMOVE "${CACHE_FILE_NAME}")
2292 endif()
2293 set(CMAKE_FILES_DIR "${CTEST_BINARY_DIRECTORY}/CMakeFiles/")
2294 if (EXISTS "${CMAKE_FILES_DIR}")
2295 message("Removing existing '${CMAKE_FILES_DIR}' ...")
2296 file(REMOVE_RECURSE "${CMAKE_FILES_DIR}")
2297 endif()
2298 endif()
2299 # NOTE: Above, we have to delete the CMakeCache.txt file only after we are
2300 # sure we are going to be configuring packages. There must be a
2301 # CMakeCache.txt file present in the binary directory or the
2302 # ctest_empty_binary_directory() command will *not* actually delete the
2303 # build directory! Also, with updated versions of CMake (2.8.10 and above)
2304 # you have to delete the CMakeFiles directory in addition to the
2305 # CMakeCache.txt file or it will not configure correctly (due to Fortran/C
2306 # linkage tests for one).
2307
2308 message(
2309 "\n***"
2310 "\n*** Uploading update, notes, and the subproject dependencies XML files ..."
2311 "\n***\n"
2312 )
2313
2314 # Set up a list of notes files that don't include the CMakeCache.clean.txt
2315 # file which will change for every submit in the package-by-package mode.
2316
2317 set(CTEST_NOTES_FILES_WO_CACHE)
2318
2319 set(REPO_VERSION_FILE "${CTEST_BINARY_DIRECTORY}/${PROJECT_NAME}RepoVersion.txt")
2320
2321 set(MULTIREPO_GIT_UPDATES_FILE "${CTEST_BINARY_DIRECTORY}/Updates.txt" )
2322 if (EXISTS "${MULTIREPO_GIT_UPDATES_FILE}")
2323 list(APPEND CTEST_NOTES_FILES_WO_CACHE "${MULTIREPO_GIT_UPDATES_FILE}")
2324 endif()
2325
2326 if (EXISTS "${CTEST_UPDATE_COMMANDS_OUTPUT_FILE}")
2327 list(APPEND CTEST_NOTES_FILES_WO_CACHE "${CTEST_UPDATE_COMMANDS_OUTPUT_FILE}" )
2328 endif()
2329
2330 # Tack on any notes files that the client might have set to the end of these
2331 print_var(CTEST_NOTES_FILES_INPUT_BY_USER)
2332 if (NOT "${CTEST_NOTES_FILES_INPUT_BY_USER}" STREQUAL "")
2333 list(APPEND CTEST_NOTES_FILES_WO_CACHE "${CTEST_NOTES_FILES_INPUT_BY_USER}")
2334 endif()
2335
2336 print_var(CTEST_NOTES_FILES_WO_CACHE)
2337
2338 # Note: We must only do the submit after we have decided if there are any
2339 # packages to enable or not and otherwise exit the script!
2340
2341 if (UPDATE_FAILED)
2342 message(SEND_ERROR
2343 "The VC update failed so submitting update so don't perform any extra actions!")
2344 if (CTEST_DO_SUBMIT)
2345 set(CTEST_NOTES_FILES "${CTEST_NOTES_FILES_WO_CACHE}")
2346 tribits_ctest_submit( PARTS update notes )
2347 endif()
2348 endif()
2349
2350 if (CTEST_DO_SUBMIT AND EXISTS ${CDASH_SUBPROJECT_XML_FILE})
2351 tribits_ctest_submit( FILES ${CDASH_SUBPROJECT_XML_FILE})
2352 message("\nSubmitted subproject dependencies XML file!")
2353 else()
2354 message("\nSkipping submitted subproject dependencies XML file on request!")
2355 endif()
2356
2357 message(
2358 "\n***"
2359 "\n*** Configure, build, test, and submit results for ${PROJECT_NAME} packages:"
2360 "\n***")
2361
2362 set(CMAKE_CACHE_CLEAN_FILE "${CTEST_BINARY_DIRECTORY}/CMakeCache.clean.txt")
2363 set(${PROJECT_NAME}_FAILED_PACKAGES)
2364
2365 if (UPDATE_FAILED)
2366
2367 message("\nUpdate failed so skipping any further actions!\n")
2368
2369 elseif(
2370 CTEST_DO_CONFIGURE
2371 OR
2372 CTEST_DO_BUILD
2373 OR
2374 CTEST_DO_TEST
2375 OR
2376 CTEST_DO_MEMORY_TESTING
2377 )
2378
2379 if (${PROJECT_NAME}_CTEST_DO_ALL_AT_ONCE)
2380
2381 tribits_ctest_all_at_once()
2382
2383 else()
2384
2385 tribits_ctest_package_by_package()
2386
2387 endif()
2388
2389 else()
2390
2391 message("\nSkipping processing anything else since not requested to"
2392 " configure, build, test, or run memory tests!\n")
2393
2394 endif()
2395
2396 if(${PROJECT_NAME}_FAILED_PACKAGES)
2397 message(
2398 "\nFinal set of packages that had any failures:"
2399 " '${${PROJECT_NAME}_FAILED_PACKAGES}'")
2400 endif()
2401
2402 # Write a file listing the packages that failed. This will be read in on the next CI
2403 # iteration since these packages must be enabled
2404 file(WRITE "${FAILED_PACKAGES_FILE_NAME}" "${${PROJECT_NAME}_FAILED_PACKAGES}\n")
2405
2406 report_queued_errors()
2407
2408 message("\nSee results submitted on CDash at the following links:\n\n"
2409 "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n\n"
2410 "${CDASH_RESULTS_STRING}\n"
2411 "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n"
2412 )
2413
2414 if ((NOT UPDATE_FAILED) AND ("${${PROJECT_NAME}_FAILED_PACKAGES}" STREQUAL ""))
2415 message(
2416 "${SEE_CDASH_LINK_STR}\n"
2417 "TRIBITS_CTEST_DRIVER: OVERALL: ALL PASSED\n")
2418 else()
2419 # ToDo: Find out why other breaking tests don't fail when FATAL_ERROR is
2420 # removed!
2421 message(FATAL_ERROR
2422 "${SEE_CDASH_LINK_STR}\n"
2423 "TRIBITS_CTEST_DRIVER: OVERALL: ALL FAILED\n")
2424 # NOTE: FATAL_ERROR is needed so that the ctest -S script returns != 0
2425 # Also, it is critical to display the "See results" in this
2426 # message(FATAL_ERROR ...) command in order for it to be printed last.
2427 # Otherwise, if you run with ctest -V -S, then the output from
2428 # ctest_test() will be printed last :-(
2429 endif()
2430
2431 endfunction()