Debian Codegraph @

cmake/tribits/ci_support/checkin-test.py

raw
1 #!/usr/bin/env python3
2
3 # @HEADER
4 # *****************************************************************************
5 # TriBITS: Tribal Build, Integrate, and Test System
6 #
7 # Copyright 2013-2016 NTESS and the TriBITS contributors.
8 # SPDX-License-Identifier: BSD-3-Clause
9 # *****************************************************************************
10 # @HEADER
11
12 #
13 # Imports
14 #
15
16 import os
17 import sys
18 import traceback
19 from optparse import OptionParser
20
21 if os.environ.get("TRIBITS_CHECKIN_TEST_DEBUG_DUMP", "") == "ON":
22 debugDump = True
23 else:
24 debugDump = False
25
26 if debugDump:
27 print("NOTE: TRIBITS_CHECKIN_TEST_DEBUG_DUMP=ON set in env, doing debug dump ...")
28
29 thisFilePath = __file__
30 if debugDump: print("\nthisFilePath =", thisFilePath)
31
32 thisFileRealAbsBasePath = os.path.dirname(os.path.abspath(os.path.realpath(thisFilePath)))
33 if debugDump: print("\nthisFileRealAbsBasePath = '"+thisFileRealAbsBasePath+"'")
34
35 from CheckinTest import *
36 from GeneralScriptSupport import *
37 from gitdist import addOptionParserChoiceOption
38
39 #
40 # Utility classes and functions.
41 #
42
43 usageHelp = r"""checkin-test.py [OPTIONS]
44
45 This tool does testing of a TriBITS-based project using CTest and this script
46 can actually do the push itself using git in a safe way. In fact, it is
47 recommended that one uses this script to push since it will amend the last
48 commit message with a (minimal) summary of the builds and tests run with
49 results and/or send out a summary email about the builds/tests performed.
50
51
52 QUICKSTART
53 -----------
54
55 In order to do a safe push, perform the following recommended workflow
56 (different variations on this workflow are described in the COMMON USE CASES
57 section below):
58
59 1) Commit changes in the local repo:
60
61 # 1.a) See what files are changed, newly added, etc.
62 $ git status
63
64 # 1.b) Stage the files you want to commit
65 $ git stage <files you want to commit>
66
67 # 1.c) Create your local commits
68 $ git commit -- SOMETHING
69 $ git commit -- SOMETHING_ELSE
70 ...
71
72 # 1.d) Stash whatever changes are left you don't want to test/push
73 $ git stash
74
75 NOTE: You can group your commits any way that you would like (see the basic
76 git documentation).
77
78 NOTE: When multiple repos are involved, use the 'gitdist' command instead of
79 'git'. This script is provided at tribits/python_utils/gitdist. See
80 gitdist --help for details.
81
82 2) Review the changes that you have made to make sure it is safe to push:
83
84 $ cd $PROJECT_HOME
85 $ git local-stat | less # Look at the full status of local repo
86 $ git diff --name-status HEAD ^@{u} # [Optional] Look at the files that have changed
87
88 NOTE: The command 'local-stat' is a git alias that can be installed with the
89 script tribits/python_utils/git-config-alias.sh. This command is
90 recommended over just a raw 'git status' or 'git log' to review commits
91 before attempting to test/push commits. If you have not installed these
92 alias, then run the following commands instead:
93
94 $ git status
95 $ git log --oneline --name-status HEAD ^@{u}
96
97 NOTE: If you see any files/directories that are listed as 'unknown' returned
98 from 'git local-stat', then you will need to do an 'git add' to track them or
99 add them to an ignore list *before* you run the checkin-test.py script.
100 The git script will not allow you to push if there are new 'unknown' files or
101 uncommitted changes to tracked files.
102
103 NOTE: When multiple repos are involved, use 'gitdist-mod-status' to see the
104 state of your repos before pushing. See gitdist --help for details.
105
106 3) Set up the checkin base build directory (first time only):
107
108 $ cd $PROJECT_HOME
109 $ echo CHECKIN >> .git/info/exclude
110 $ mkdir CHECKIN
111 $ cd CHECKIN
112
113 NOTE: You may need to set up some configuration files if CMake cannot find
114 the right compilers, MPI, and TPLs by default (see detailed documentation
115 below).
116
117 NOTE: You might want to set up a simple shell driver script for your common
118 use cases.
119
120 NOTE: You can set up a CHECKIN directory of any name in any location
121 you want. If you create one outside of the main source dir, then
122 you will not have to add the git exclude shown above.
123
124 4) Do the pull, configure, build, test, and push:
125
126 $ cd $PROJECT_HOME
127 $ cd CHECKIN
128 $ ../checkin-test.py -j4 --do-all --push
129
130 NOTE: The above will: a) pull updates from the tracking branch, b)
131 automatically enable the correct packages based on changed files, c)
132 configure and build the changed and downstream packages, d) run the tests,
133 e) send you emails about what happened, f) do a final pull from the global
134 repo, g) optionally amend the last local commit with the test results, and
135 h) finally push local commits to the tracking branch if everything passes.
136
137 NOTE: The repo must be on a branch (not a detached head state) with a
138 tracking branch '<remoterepo>/<remotebranch>' so that a raw 'git pull' can
139 be performed to get updates and to push changes. Also, the push is done
140 explicitly to the tracking branch using:
141
142 git push <remoterepo> <remotebranch>
143
144 NOTE: You must not have any uncommitted changes or the script will stop
145 right away. To run the script, you will may need to first use 'git stash'
146 to stash away your unstagged/uncommitted changes *before* running this
147 script.
148
149 NOTE: You need to have SSH public/private keys set up to the remote repo
150 machines for the git commands invoked in the script to work without you
151 having to type a password. If the 'git pull' fails, the detailed output is
152 generally in a pull*.out file (see the checkin-test.out log file for
153 details).
154
155 NOTE: You can do the final push in a second invocation of the script with a
156 follow-up run with --push and removing --do-all (it will remember the
157 results from the build/test cases just ran). For more details, see detailed
158 documentation below.
159
160 NOTE: Once you start running the checkin-test.py script, you can go off and
161 do something else and just check your email to see if all the builds and
162 tests passed and if the push happened or not.
163
164 NOTE: The commands 'cmake', 'ctest', and 'make' must be in your default path
165 before running this script.
166
167 NOTE: Defaults like -j4 can be set using a local-checkin-test-defaults.py
168 file (see below).
169
170 For more details on using this script, see the detailed documentation below.
171
172
173 DETAILED DOCUMENTATION
174 -----------------------
175
176 The following approximate steps are performed by this script:
177
178 ----------------------------------------------------------------------------
179
180 1) Check to see if the local repo(s) are clean:
181
182 $ git status
183
184 NOTE: If any modified or any unknown files are shown, the process will be
185 aborted. The local repo(s) working directory must be clean and ready to
186 push *everything* that is not stashed away.
187
188 2) Do a 'git pull' to update the repo (done if --pull or --do-all is set):
189
190 NOTE: If not doing a pull, use --allow-no-pull or --local-do-all.
191
192 3) Select the list of packages to enable forward/downstream based on the
193 package directories where there are changed files (or from a list of packages
194 passed in by the user).
195
196 NOTE: The automatic enable behavior can be overridden or modified using the
197 options --enable-all-packages=on/off, --enable-packages=<p0>,<p1>,... ,
198 --disable-packages=<p0>,<p1>,... , and/or --no-enable-fwd-packages.
199
200 4) For each build/test case <BUILD_NAME> (e.g. MPI_DEBUG, SERIAL_RELEASE,
201 extra builds specified with --st-extra-builds and --extra-builds):
202
203 4.a) Configure a build directory <BUILD_NAME> in a standard way for all of
204 the packages that have changed and all of the packages that depend on these
205 packages forward/downstream. You can manually select which packages get
206 enabled (see the enable options above). (done if --configure, --do-all, or
207 --local-do-all is set.)
208
209 4.b) Build all configured code with 'make' (e.g. with -jN set through
210 -j or --make-options). (done if --build, --do-all, or --local-do-all is set.)
211
212 4.c) Run all BASIC tests for enabled packages. (done if --test, --do-all,
213 or --local-do-all is set.)
214
215 4.d) Analyze the results of the pull, configure, build, and tests and send
216 email about results. (emails only sent out if --send-emails-to!="")
217
218 5) Do final pull and rebase, append test results to last commit message, and
219 push (done if --push or --do-all is set)
220
221 5.a) Do a final 'git pull' (done if --pull or --do-all is set)
222
223 5.b) Do 'git rebase <remoterepo>/<remotebranch>' (done if --rebase is set)
224
225 5.c) Amend commit message of the most recent commit with the summary of the
226 testing performed. (done if --append-test-results is set.)
227
228 5.d) Push the local commits to the global repo (done if --push is set)
229
230 6) Send out final on actions (i.e. 'DID PUSH' email if a push occurred).
231 (done if --send-email-to!="" is set and --send-email-only-on-failure is *not*
232 set)
233
234 ----------------------------------------------------------------------------
235
236 The recommended way to use this script is to create a new base CHECKIN test
237 directory apart from your standard build directories such as with:
238
239 $ $PROJECT_HOME
240 $ mkdir CHECKIN
241 $ echo CHECKIN >> .git/info/exclude
242
243 The most basic way to do pre-push testing is with:
244
245 $ cd CHECKIN
246 $ ../checkin-test.py --do-all [other options]
247
248 If your MPI installation, other compilers, and standard TPLs can be found
249 automatically, then this is all you will need to do. However, if the setup
250 cannot be determined automatically, then you can add a set of CMake variables
251 that will get read in the files:
252
253 COMMON.config
254 MPI_DEBUG.config
255 SERIAL_RELEASE.config
256
257 (or whatever your standard --default-builds are).
258
259 Actually, for built-in build/test cases, skeletons of these files will
260 automatically be written out with typical CMake cache variables (commented
261 out) that you would need to set out. Any CMake cache variables listed in
262 these files will be read into and passed on the configure line to 'cmake'.
263
264 WARNING: Please do not add any extra CMake cache variables than what are
265 needed to get the Primary Tested (PT) --default-builds builds to work. Adding
266 other enables/disables will make the builds non-standard and can break these
267 PT builds. The goal of these configuration files is to allow you to specify
268 the minimum environment to find MPI, your compilers, and the required TPLs
269 (e.g. BLAS, LAPACK, etc.). If you need to fudge what packages are enabled,
270 please use the script arguments --enable-packages, --enable-extra-pacakges,
271 --disable-packages, --no-enable-fwd-packages, and/or --enable-all-packages to
272 control this, not the *.config files!
273
274 WARNING: Please do not add any CMake cache variables in the *.config files
275 that will alter what packages or TPLs are enabled or what tests are run.
276 Actually, the script will not allow you to change TPL enables in these
277 standard *.config files because to do so deviates from a consistent build
278 configuration for Primary Tested (PT) Code.
279
280 NOTE: All tentatively-enabled TPLs (e.g. Pthreads and BinUtils) are hard
281 disabled in order to avoid different behaviors between machines where they
282 would be enabled and machines where they would be disabled.
283
284 NOTE: If you want to add extra build/test cases that do not conform to
285 the standard build/test configurations described above, then you need
286 to create extra builds with the --extra-builds and/or
287 --st-extra-builds options (see below).
288
289 NOTE: Before running this script, you should first do an 'git status' and 'git
290 diff --name-status HEAD ^@{u}' and examine what files are changed to make sure
291 you want to push what you have in your local working directory. Also, please
292 look out for unknown files that you may need to add to the git repository with
293 'git add' or add to your ignores list. There cannot be any uncommitted
294 changes in the local repo before running this script.
295
296 NOTE: You don't need to run this script if you have not changed any files that
297 affect the build or the tests. For example, if all you have changed are
298 documentation files, then you don't need to run this script before pushing
299 manually.
300
301 NOTE: To see detailed debug-level information, set
302 TRIBITS_CHECKIN_TEST_DEBUG_DUMP=ON in the env before running this script.
303
304
305 COMMON USE CASES (EXAMPLES):
306 ----------------------------
307
308 (*) Basic full testing with integrating with global repo(s) without push:
309
310 ../checkin-test.py --do-all
311
312 NOTE: This will result in a set of emails getting sent to your email address
313 for the different configurations and an overall push readiness status email.
314
315 NOTE: If everything passed, you can follow this up with a --push (see
316 below).
317
318 (*) Basic full testing with integrating with local repo and push:
319
320 ../checkin-test.py --do-all --push
321
322 NOTE: By default this will rebase your local commits and amend the last
323 commit with a short summary of test results. This is appropriate for
324 pushing commits that only exist in your local repo and are not shared with
325 any remote repo.
326
327 (*) Push to global repo after a completed set of tests have finished:
328
329 ../checkin-test.py [other options] --push
330
331 NOTE: This will pick up the results for the last completed test runs with
332 [other options] and append the results of those tests to the log of the most
333 recent commit.
334
335 NOTE: Take the action options for the prior run and replace --do-all with
336 --push but keep all of the rest of the options the same. For example, if
337 you did:
338
339 ../checkin-test.py --enable-packages=Blah --default-builds=MPI_DEBUG --do-all
340
341 then follow that up with:
342
343 ../checkin-test.py --enable-packages=Blah --default-builds=MPI_DEBUG --push
344
345 NOTE: This is a common use case when some tests are failing which aborted
346 the initial push but you determine it is okay to push anyway and do so with
347 --force-push.
348
349 (*) Test only the packages modified and not the forward dependent packages:
350
351 ../checkin-test.py --do-all --no-enable-fwd-packages
352
353 NOTE: This is a safe thing to do when only tests in the modified packages
354 are changed and not library code. This can speed up the testing process and
355 is to be preferred over not running this script at all. It would be very
356 hard to make this script automatically determine if only test code has
357 changed because every package does not follow a set pattern for
358 tests and test code.
359
360 (*) Run the most important default (e.g. MPI_DEBUG) build/test only:
361
362 ../checkin-test.py --do-all --default-builds=MPI_DEBUG
363
364 (*) The minimum acceptable testing when code has been changed:
365
366 ../checkin-test.py \
367 --do-all --enable-all-packages=off --no-enable-fwd-packages \
368 --default-builds=MPI_DEBUG
369
370 NOTE: This will do only an MPI DEBUG build and will only build and run the
371 tests for the packages that have directly been changed and not any forward
372 packages. Replace "MPI_DEBUG" with whatever your most important default
373 build is.
374
375 (*) Test only a specific set of packages and no others:
376
377 ../checkin-test.py \
378 --enable-packages=<P0>,<P1>,<P2> --no-enable-fwd-packages \
379 --do-all
380
381 NOTE: This will override all logic in the script about which packages will
382 be enabled based on file changes and only the given packages will be
383 enabled. When there are tens of thousands of changed files and hundreds of
384 defined packages, this auto-detection algorithm can be very expensive!
385
386 NOTE: You might also want to pass in --enable-all-packages=off in case the
387 script wants to enable all the packages (see the output in the
388 checkin-test.py log file for details) and you think it is not necessary to
389 do so.
390
391 NOTE: Using these options is greatly preferred to not running this script at
392 all and should not be any more expensive than the testing you would already
393 do manually before a push.
394
395 (*) Test changes locally without pulling updates:
396
397 ../checkin-test.py --local-do-all
398
399 NOTE: This will just configure, build, test, and send an email notification
400 without updating or changing the status of the local git repo in any way and
401 without any communication with the global repo. Hence, you can have
402 uncommitted changes and still run configure, build, test without having to
403 commit or having to stash changes.
404
405 NOTE: This will determine what packages to enable and test based on changes
406 w.r.t. to the tracking branch. If not on a tracking branch, or in a
407 detached head state, see below.
408
409 NOTE: This is typically not a sufficient level of testing in order to push
410 the changes to a shared branch because you have not fully integrated your
411 changes yet with other developers. However, this would be a sufficient
412 level of testing in order to do a commit on the local machine and then pull
413 to a remote machine for further testing and a push (see below).
414
415 (*) Local test of repo version on a detached head or with no tracking branch:
416
417 ../checkin-test.py --enable-all-packages=[on|off] \
418 --enable-packages=<P0>,... --local-do-all
419
420 By specifying what packages are enabled and not doing a pull or push, the
421 script allows the repo(s) to be in a detached head state or on a branch that
422 does not have a tracking branch. This allows the checkin-test.py script to
423 be used, for example, to test versions using 'git bisect'.
424
425 (*) Adding extra build/test cases:
426
427 Often you will be working on Secondary Tested (ST) Code or Experimental (EX)
428 Code and want to include the testing of this in your pre-push testing
429 process along with the standard --default-builds build/test cases which can
430 only include Primary Tested (PT) Code. In this case you can run with:
431
432 ../checkin-test.py --extra-builds=<BUILD1>,<BUILD2>,... [other options]
433
434 For example, if you have a build that enables the TPL CUDA you would do:
435
436 echo "
437 -DTPL_ENABLE_MPI:BOOL=ON
438 -DTPL_ENABLE_CUDA:BOOL=ON
439 " > MPI_DEBUG_CUDA.config
440
441 and then run with:
442
443 ../checkin-test.py --extra-builds=MPI_DEBUG_CUDA --do-all
444
445 This will do the standard --default-builds (e.g. MPI_DEBUG and
446 SERIAL_RELEASE) build/test cases along with your non-standard MPI_DEBUG_CUDA
447 build/test case.
448
449 NOTE: You can disable the default build/test cases with --default-builds="".
450 However, please only do this when you are not going to push because you need
451 at least one default build/test case (the most important default PT case,
452 e.g. MPI_DEBUG) to do a safe push.
453
454 (*) Including extra repos and extra packages:
455
456 You can also use the checkin-test.py script to continuously integrate
457 multiple git repos containing add-on packages. To do so, just run:
458
459 ../checkin-test.py --extra-repos=<REPO1>,<REPO2>,... [options]
460
461 NOTE: You have to create local commits in all of the extra repos where there
462 are changes or the script will abort.
463
464 NOTE: Extra repos can be specified with more flexibility using the
465 --extra-repos-file and --extra-repos-type arguments (also see
466 --ignore-missing-extra-repos).
467
468 NOTE: Each of the last local commits in each of the changed repos will get
469 amended with the appended summary of what was enabled in the build/test (if
470 --append-test-results is set).
471
472 (*) Avoid changing any of the local commit SHA1s:
473
474 If you are pushing commits from a shared branch, it is critical that you do
475 not change any of the SHA1s of the commits. Changing the SHA1s for any of
476 the commits will mess up various multi-repo, multi-branch workflows. To
477 avoid changing any of the SHA1s of the local commits, one must run with:
478
479 ../checkin-test.py --no-rebase --no-append-test-results [options]
480
481 (*) Performing a remote test/push:
482
483 If you develop on a slow machine like your laptop, doing an appropriate
484 level of testing can take a long time. In this case, you can pull the
485 changes to another faster remote workstation and do a more complete set of
486 tests and push from there. If you are knowledgeable with git, this will be
487 easy and natural to do, without any help from this script. However, this
488 script can still help and automate the steps and can do so in one command
489 invocation on the part of the developer.
490
491 On your slow local development machine 'mymachine', do the limited testing
492 with:
493
494 ../checkin-test.py --do-all --no-enable-fwd-packages
495
496 On your fast remote test machine, do a full test and push with:
497
498 ../checkin-test.py \
499 --extra-pull-from=<remote-repo>:master \
500 --do-all --push
501
502 where <remote-name> is a git remote repo name pointing to
503 mymachine:/some/dir/to/your/src (see 'git help remote').
504
505 NOTE: You can of course adjust the packages and/or build/test cases that get
506 enabled on the different machines.
507
508 NOTE: Once you invoke the checkin-test.py script on the remote test machine
509 and it has pulled the commits from mymachine, then you can start changing
510 files again on your local development machine and just check your email to
511 see what happens on the remote test machine.
512
513 NOTE: If something goes wrong on the remote test machine, you can either
514 work on fixing the problem there or you can fix the problem on your local
515 development machine and then do the process over again.
516
517 NOTE: If you alter the commits on the remote machine (such as squashing
518 commits), you will have trouble merging back on our local machine.
519 Therefore, if you have to to fix problems, make new commits and don't alter
520 the ones you pulled from your local machine (but rebasing them should be
521 okay as long as the local commits on mymachine are not pushed to other
522 repos).
523
524 NOTE: Git will resolve the duplicated commits when you pull the commits
525 pushed from the remote machine. Git knows that the commits are the same and
526 will do the right thing when rebasing (or just merging).
527
528 NOTE: This would also work for multiple repos if the remote name
529 '<remote-repo>' pointed to the right remote repo in all the local repos.
530
531 (*) Check push readiness status:
532
533 ../checkin-test.py
534
535 This will examine results for the last testing process and send out an email
536 stating if the a push is ready to perform or not.
537
538 (*) See the default option values without doing anything:
539
540 ../checkin-test.py --show-defaults
541
542 This is the easiest way to figure out what all of the default options are.
543
544 Hopefully the above documentation, the example use cases, the documentation of
545 the command-line arguments below, and some experimentation will be enough to
546 get you going using this script for all of your pre-push testing and pushes.
547 If that is not sufficient, send email to your development support team to ask
548 for help.
549
550
551 LOCAL DEFAULT COMMAND LINE DEFAULTS
552 -----------------------------------
553
554 If the file local-checkin-test-defaults.py exists in the current directory,
555 then it will be read in and will change the project defaults for the
556 command-line arguments. For example, a valid local-checkin-test-defaults.py
557 file would look like:
558
559 defaults = [
560 "-j10",
561 "--no-rebase",
562 "--ctest-options=-E '(PackageA_Test1|PackageB_Test2)'"
563 ]
564
565 Any of the project's checkin-test.py command-line argument defaults can be
566 changed in this way. The updated defaults can be observed by running:
567
568 ./checkin-test.py --show-defaults
569
570 Any command-line arguments explicitly passed in will override these local
571 defaults.
572
573
574 HANDLING OF PT, ST, AND EX CODE IN BUILT-IN AND EXTRA BUILDS:
575 -------------------------------------------------------------
576
577 This script will only process PT (Primary Tested) packages in the
578 --default-builds (e.g. MPI_DEBUG and SERIAL_RELEASE) builds. This is to avoid
579 problems of side-effects of turning on ST packages that would impact PT
580 packages (e.g. an ST package getting enabled that enables an ST TPL which
581 turns on support for that TPL in a PT package producing different code which
582 might work but the pure PT build without the extra TPL may actually be broken
583 and not know it). Therefore, any non-PT packages that are enabled (either
584 implicitly through changed files or explicitly by listing in --enable-packages)
585 will be turned off in the --default-builds builds. If none of the enabled
586 packages are PT, then they will all be disabled and the --default-builds
587 builds will be skipped.
588
589 In order to better support the development of ST and EX packages, this script
590 allows you to define some extra builds that will be invoked and used to
591 determine overall pass/fail before a potential push. The option
592 --st-extra-builds is used to specify extra builds that will test ST packages
593 (and also PT packages if any are enabled). If only PT packages are enabled
594 then the builds specified in --st-extra-builds will still be run. The
595 reasoning is that PT packages may contain extra ST features and therefore if
596 the goal is to test these ST builds it is desirable to also run these builds
597 because they also my impact downstream ST packages.
598
599 Finally, the option --extra-builds will test all enabled packages, including
600 EX packages, regardless of their test group. Therefore, when using
601 --extra-builds, be careful that you watch what packages are enabled. If you
602 change an EX package, it will be enabled in --extra-builds builds.
603
604 A few use cases might help better demonstrate the behavior. Consider
605 the following input arguments specifying extra builds
606
607 --st-extra-builds=MPI_DEBUG_ST --extra-builds=INTEL_DEBUG
608
609 with the packages Teuchos, Phalanx, and Meros where Teuchos is PT, Phalanx is
610 ST, and Meros is EX.
611
612 Here is what packages would be enabled in each of the builds:
613
614 --default-builds=MPI_DEBUG,SERIAL_RELEASE \
615 --st-extra-builds=MPI_DEBUG_ST \
616 --extra-builds=INTEL_DEBUG
617
618 and which packages would be excluded:
619
620 A) --enable-packages=Teuchos:
621 MPI_DEBUG: [Teuchos]
622 SERIAL_RELEASE: [Teuchos]
623 MPI_DEBUG_ST: [Teuchos]
624 INTEL_DEBUG: [Teuchos] Always enabled!
625
626 B) --enable-packages=Phalanx:
627 MPI_DEBUG: [] Skipped, no PT packages!
628 SERIAL_RELEASE: [] Skipped, no PT packages!
629 MPI_DEBUG_ST: [Phalanx]
630 INTEL_DEBUG: [Phalanx]
631
632 C) --enable-packages=Meros:
633 MPI_DEBUG: [] Skipped, no PT packages!
634 SERIAL_RELEASE: [] Skipped, no PT packages!
635 MPI_DEBUG_ST: [] Skipped, no PT or ST packages!
636 INTEL_DEBUG: [Meros]
637
638 D) --enable-packages=Teuchos,Phalanx:
639 MPI_DEBUG: [Teuchos]
640 SERIAL_RELEASE: [Teuchos]
641 MPI_DEBUG_ST: [Teuchos,Phalanx]
642 INTEL_DEBUG: [Teuchos,Phalanx]
643
644 E) --enable-packages=Teuchos,Phalanx,Meros:
645 MPI_DEBUG: [Teuchos]
646 SERIAL_RELEASE: [Teuchos]
647 MPI_DEBUG_ST: [Teuchos,Phalanx]
648 INTEL_DEBUG: [Teuchos,Phalanx,Meros]
649
650 The --extra-builds=INTEL_DEBUG build is always performed with all of the
651 enabled packages. This logic given above must be understood in order to
652 understand the output given in the script.
653
654
655 CONVENTIONS FOR COMMAND-LINE ARGUMENTS:
656 ---------------------------------------
657
658 The command-line arguments are segregated into three broad categories: a)
659 action commands, b) aggregate action commands, and c) others.
660
661 a) The action commands are those such as --build, --test, etc. and are shown
662 with [ACTION] in their documentation. These action commands have no off
663 complement. If the action command appears, then the action will be performed.
664
665 b) Aggregate action commands such as --do-all and --local-do-all turn on sets
666 of other action commands and are shown with [AGGR ACTION] in their
667 documentation. The sub-actions that these aggregate action commands turn on
668 cannot be disabled with other arguments.
669
670 c) Other arguments are those that are not marked with [ACTION] or [AGGR
671 ACTION] tend to either pass in data and turn control flags on or off.
672
673
674 EXIT CODE:
675 ---------
676
677 This script returns 0 if the actions requested are successful. This does not
678 necessarily imply that it is okay to do a push or that a push was done. For
679 example, if only --pull is passed in and is successful, then 0 will be
680 returned but that does *not* mean that it is okay to do a push. Therefore, a
681 return value of is a necessary but not sufficient condition for readiness to
682 push, it depends on the requested actions.
683
684 """
685
686 # ToDo: Break up the above huge documentation block into different "topics"
687 # and then display those topics with --help-topic=<topic>. Also provide a
688 # --help-all that will combine all of the --help-topic documentation with the
689 # standard documentation to produce where is there now.
690
691 def runProjectTestsWithCommandLineArgs(commandLineArgs, configuration = {}):
692
693 clp = ConfigurableOptionParser(configuration.get('defaults', {}), usage=usageHelp)
694
695 clp.add_option(
696 "--project-configuration", dest="projectConfiguration", type="string", default="",
697 help="Custom file to provide configuration defaults for the project." \
698 + " By default, the file project-checkin-test-config.py is looked for" \
699 + " in <checkin-test-path> (in case it is symlinked into <projectDir>/checkin-test.py)" \
700 + " if not found there, then it is looked for in <checkin-test-path>/../../.." \
701 +" (assuming default TriBITS snapshot <projectDir>/cmake/tribits/ci_support/)" \
702 + " If this file is set to a location that is not in the" \
703 + " project's base directory, then --src-dir must be set to point to the" \
704 + " project's base directory."
705 )
706
707 clp.add_option(
708 "--show-defaults", dest="showDefaults", action="store_true",
709 help="Show the default option values and do nothing at all.",
710 default=False )
711
712 clp.add_option(
713 "--project-name", dest="projectName", action="store",
714 help="Set the project's name. This is used to locate various files."+\
715 " If not set, then it reads the project name from the PROJECT_NAME"+\
716 " variable set in the file SRCDIR/ProjectName.cmake.",
717 default=None)
718
719 clp.add_option(
720 '--src-dir', dest="srcDir", type="string", default="",
721 help="The source base directory for code to be tested. The default is determined" \
722 +" by the location of the found project-checkin-test-config.py file." )
723
724 configuredBuilds = [build for build, unused in
725 configuration.get('cmake', {}).get('default-builds', [])]
726 clp.add_option(
727 '--default-builds', dest='defaultBuilds', type='string',
728 default=','.join(configuredBuilds),
729 help="Comma separated list of builds that should always be run by default.")
730
731 clp.add_option(
732 "--extra-repos-file", dest="extraReposFile", type="string", default="",
733 help="File path to an extra repositories list file. If set to 'project', then " \
734 +"<project_dir>/cmake/ExtraRepositoriesList.cmake is read. See the argument " \
735 +"--extra-repos for details on how this list is used (default empty '')")
736
737 g_extraRepoTypesList = [""]
738 g_extraRepoTypesList.extend(g_knownTribitsTestRepoTypes)
739
740 addOptionParserChoiceOption(
741 "--extra-repos-type", "extraReposType", g_extraRepoTypesList, 0,
742 "The test type of repos to read from <extra_repos_file>.",
743 clp )
744
745 clp.add_option(
746 "--extra-repos", dest="extraRepos", type="string", default="",
747 help="List of comma separated extra repositories " \
748 +"containing extra packages that can be enabled. The order these repos is "
749 +"listed in not important. This option overrides --extra-repos-file.")
750
751 clp.add_option(
752 "--ignore-missing-extra-repos", dest="ignoreMissingExtraRepos", action="store_true",
753 help="If set, then extra repos read in from <extra_repos_file> will be ignored " \
754 +"and removed from list. This option is not applicable if <extra_repos_file>=='' " \
755 +"or <extra_repos_type>==''." )
756 clp.add_option(
757 "--require-extra-repos-exist", dest="ignoreMissingExtraRepos", action="store_false",
758 default=False,
759 help="If set, then all listed extra repos must exist or the script will exit. [default]" )
760
761 clp.add_option(
762 "--with-cmake", dest="withCmake", type="string", default="cmake",
763 help="CMake executable to use with cmake -P scripts internally (only set" \
764 +" by unit testing code).")
765
766 clp.add_option(
767 "--skip-deps-update", dest="skipDepsUpdate", action="store_true",
768 help="If set, skip the update of the dependency XML file. If the package structure" \
769 " has not changed since the last invocation, then it is safe to use this option.",
770 default=False )
771
772 clp.add_option(
773 "--enable-packages", dest="enablePackages", type="string", default="",
774 help="List of comma separated packages to test changes for" \
775 +" (example, 'Teuchos,Epetra'). If this list of packages is empty, then" \
776 +" the list of packages to enable will be determined automatically by examining" \
777 +" the set of modified files from the version control update log. Note that"\
778 +" this will skip the auto-detection of changed packages based on changed"\
779 +" files." )
780
781 clp.add_option(
782 "--enable-extra-packages", dest="enableExtraPackages", type="string", default="",
783 help="List of comma separated packages to test in addition to the packages" \
784 +" that are enabled determined automatically by examining" \
785 +" the set of modified files from the version control update log. This option"\
786 +" is mostly just used in ACI sync servers." )
787
788 clp.add_option(
789 "--disable-packages", dest="disablePackages", type="string", default="",
790 help="List of comma separated packages to explicitly disable" \
791 +" (example, 'Tpetra,NOX'). This list of disables will be appended after" \
792 +" all of the listed enables no matter how they are determined (see" \
793 +" --enable-packages option). NOTE: Only use this option to remove packages" \
794 +" that will not build for some reason. You can disable tests that run" \
795 +" by using the CTest option -E passed through the --ctest-options argument" \
796 +" in this script." )
797
798 addOptionParserChoiceOption(
799 "--enable-all-packages", "enableAllPackages", ('auto', 'on', 'off'), 0,
800 "Determine if all packages are enabled 'on', or 'off', or 'auto'" \
801 +" (let other logic decide). Setting to 'off' is appropriate when" \
802 +" the logic in this script determines that a global build file has changed" \
803 +" but you know that you don't need to rebuild and test every package for" \
804 +" a reasonable test. Setting --enable-packages effectively disables this" \
805 +" option. Setting this to 'off' does *not* stop the forward enabling" \
806 +" of downstream packages for packages that are modified or set by --enable-packages."\
807 +" Setting this to 'on' will skip the automatic detection of changed packages"\
808 +" based on changed files. It can be helpful to stop the auto-detection changed"\
809 +" packages when there are thousands of changed files and hundreds of defined"\
810 +" packages." ,
811 clp )
812
813 clp.add_option(
814 "--enable-fwd-packages", dest="enableFwdPackages", action="store_true",
815 help="Enable forward packages. [default]" )
816 clp.add_option(
817 "--no-enable-fwd-packages", dest="enableFwdPackages", action="store_false",
818 help="Do not enable forward packages.", default=True )
819
820 clp.add_option(
821 "--continue-if-no-updates", dest="abortGracefullyIfNoChangesPulled", action="store_false",
822 help="If set, then the script will continue if no updates are pulled from any repo. [default]",
823 default=False )
824 clp.add_option(
825 "--abort-gracefully-if-no-changes-pulled", dest="abortGracefullyIfNoChangesPulled", action="store_true",
826 help="If set, then the script will abort gracefully if no updates are pulled from any repo.",
827 default=False )
828
829 clp.add_option(
830 "--continue-if-no-changes-to-push", dest="abortGracefullyIfNoChangesToPush", action="store_false",
831 help="If set, then the script will continue if no changes to push from any repo. [default]",
832 default=False )
833 clp.add_option(
834 "--abort-gracefully-if-no-changes-to-push", dest="abortGracefullyIfNoChangesToPush", action="store_true",
835 help="If set, then the script will abort gracefully if no changes to push from any repo.",
836 default=False )
837
838 clp.add_option(
839 "--continue-if-no-enables", dest="abortGracefullyIfNoEnables", action="store_false",
840 help="If set, then the script will continue if no packages are enabled. [default]",
841 default=False )
842 clp.add_option(
843 "--abort-gracefully-if-no-enables", dest="abortGracefullyIfNoEnables", action="store_true",
844 help="If set, then the script will abort gracefully if no packages are enabled.",
845 default=False )
846
847 clp.add_option(
848 "--extra-cmake-options", dest="extraCmakeOptions", type="string",
849 default=configuration.get('extra-cmake-options', ''),
850 help="Extra options to pass to 'cmake' after all other options." \
851 +" This should be used only as a last resort. To disable packages, instead use" \
852 +" --disable-packages. To change test categories, use --test-categories." )
853
854 clp.add_option(
855 "--test-categories", dest="testCategories", type="string",
856 default="BASIC",
857 help="." \
858 +" Change the test categories. Can be 'BASIC', 'CONTINUOUS', " \
859 " 'NIGHTLY', or 'HEAVY' (default set by project, see --show-defaults)." )
860
861 clp.add_option(
862 "-j", "--parallel", dest="overallNumProcs", type="string", default="",
863 help="The options to pass to make and ctest (e.g. -j4)." )
864
865 clp.add_option(
866 "--use-makefiles", dest="useNinja", action="store_false",
867 help="If set, then -G'Unix Makfiles' used for backend build tool." \
868 +" Note: The command 'make' must be in the default path. [default]",
869 default=False )
870 clp.add_option(
871 "--use-ninja", dest="useNinja", action="store_true",
872 help="If set, then -GNinja used for backend build tool." \
873 +" Note: The command 'ninja' must be in the default path." ,
874 default=False )
875
876 clp.add_option(
877 "--make-options", dest="makeOptions", type="string", default="",
878 help="The options to pass to 'make' (e.g. -j4) or ninja" \
879 +" (if --use-ninja given)." )
880
881 clp.add_option(
882 "--ctest-options", dest="ctestOptions", type="string", default="",
883 help="Extra options to pass to 'ctest' (e.g. -j2)." )
884
885 clp.add_option(
886 "--ctest-timeout", dest="ctestTimeOut", type="float", default=300,
887 help="timeout (in seconds) for each single 'ctest' test (e.g. 180" \
888 +" for three minutes). This sets the CMake cache var DART_TESTING_TIMEOUT"
889 +" which becomes the default timeout for tests, even when running raw"
890 +" ctest. This value can be overridden using the ctest argument --timeout."
891 +" Individual tests may have their own timeouts set which will not be"
892 +" impacted by this default global timeout. See the configure variable"
893 +" <Project>_SCALE_TEST_TIMEOUT to scale up timeouts for"
894 +" all tests, even those that have individuals timeouts set." )
895
896 clp.add_option(
897 "--show-all-tests", dest="showAllTests", action="store_true",
898 help="Show all of the tests in the summary email and in the commit message" \
899 +" summary (see --append-test-results)." )
900 clp.add_option(
901 "--no-show-all-tests", dest="showAllTests", action="store_false",
902 help="Don't show all of the test results in the summary email. [default]",
903 default=False )
904
905 clp.add_option(
906 "--without-default-builds", dest="withoutDefaultBuilds", action="store_true",
907 default=False,
908 help="Skip the default builds (same as --default-builds='')." \
909 +" You would use option along with --extra-builds=BUILD1,BUILD2,... to run your own" \
910 +" local custom builds." )
911
912 clp.add_option(
913 "--st-extra-builds", dest="stExtraBuilds", type="string", default="",
914 help="List of comma-separated ST extra build names. For each of the build names in" \
915 +" --st-extra-builds=<BUILD1>,<BUILD2>,..., there must be a file <BUILDN>.config in" \
916 +" the local directory along side the COMMON.config file that defines the special" \
917 +" build options for the extra build." )
918
919 clp.add_option(
920 "--ss-extra-builds", dest="ssExtraBuilds", type="string", default="",
921 help="DEPRECATED! Use --st-extra-builds instead!. (Default empty "")" )
922
923 clp.add_option(
924 "--extra-builds", dest="extraBuilds", type="string", default="",
925 help="List of comma-separated extra build names. For each of the build names in" \
926 +" --extra-builds=<BUILD1>,<BUILD2>,..., there must be a file <BUILDN>.config in" \
927 +" the local directory along side the COMMON.config file that defines the special" \
928 +" build options for the extra build." )
929
930 clp.add_option(
931 "--log-file", dest="logFile", type="string", default="checkin-test.out",
932 help="File used for detailed log info." )
933
934 clp.add_option(
935 "--send-email-to", dest="sendEmailTo", type="string",
936 default=getCmndOutput("git config --get user.email", True, False),
937 help="List of comma-separated email addresses to send email notification to" \
938 +" after every build/test case finishes and at the end for an overall summary" \
939 +" and push status." \
940 +" By default, this is the email address you set for git returned by" \
941 +" `git config --get user.email`. In order to turn off email" \
942 +" notification, just set --send-email-to='' and no email will be sent." )
943
944 clp.add_option(
945 "--skip-case-send-email", dest="skipCaseSendEmail", action="store_true",
946 help="If set then if a build/test case is skipped for some reason (i.e." \
947 +" because no packages are enabled) then an email will go out for that case." \
948 +" [default]" )
949 clp.add_option(
950 "--skip-case-no-email", dest="skipCaseSendEmail", action="store_false",
951 help="If set, then if a build/test case is skipped for some reason (i.e." \
952 +" because no packages are enabled) then no email will go out for that case." \
953 +" (opposite of --skip-case-send-email) [default]",
954 default=True )
955
956 addOptionParserChoiceOption(
957 "--send-build-case-email", "sendBuildCaseEmail",
958 ('always', 'only-on-failure', 'never'), 0,
959 "Determines when email goes out to --send-email-to=<email> for a build" \
960 +" case. But the final status email will still go out if --send-email-to=<email>" \
961 +" is not empty. [default = 'always']",
962 clp )
963
964 clp.add_option(
965 "--send-email-for-all", dest="sendEmailOnlyOnFailure", action="store_false",
966 help="If set, then emails will get sent out for all operations. [default]" )
967 clp.add_option(
968 "--send-email-only-on-failure", dest="sendEmailOnlyOnFailure", action="store_true",
969 help="If set, then emails will only get sent out for failures.",
970 default=False )
971
972 clp.add_option(
973 "--send-email-to-on-push", dest="sendEmailToOnPush", type="string",
974 default=configuration.get('SendEmailOnPush', ''),
975 help="List of comma-separated email addresses to send email notification to" \
976 +" on a successful push. This is used to log pushes to a central list." \
977 +" In order to turn off this email" \
978 +" notification, just set --send-email-to-on-push='' and no email will be sent" \
979 +" to these email lists." )
980
981 clp.add_option(
982 "--force-push", dest="forcePush", action="store_true",
983 help="Force the local push even if there are build/test errors." \
984 +" WARNING: Only do this when you are 100% certain that the errors are not" \
985 +" caused by your code changes. This only applies when --push is specified" \
986 +" and this script.")
987 clp.add_option(
988 "--no-force-push", dest="forcePush", action="store_false", default=False,
989 help="Do not force a push if there are failures. [default]" )
990
991 clp.add_option(
992 "--do-push-readiness-check", dest="doPushReadinessCheck", action="store_true",
993 help="Check the push readiness status at the end and send email if not actually" \
994 +" pushing. [default]" )
995 clp.add_option(
996 "--skip-push-readiness-check", dest="doPushReadinessCheck", action="store_false",
997 default=True,
998 help="Skip push status check." )
999
1000 clp.add_option(
1001 "--rebase", dest="rebase", action="store_true",
1002 help="Rebase the local commits on top of <remoterepo>/<remotebranch> before amending" \
1003 +" the last commit and pushing. Rebasing keeps a nice linear commit" \
1004 +" history like with CVS or SVN and will work perfectly for the basic" \
1005 +" workflow of adding commits to the 'master' branch and then syncing" \
1006 +" up with <remoterepo>/<remotebranch> before the final push. [default]" )
1007 clp.add_option(
1008 "--no-rebase", dest="rebase", action="store_false",
1009 help="Do *not* rebase the local commits on top of <remoterepo>/<remotebranch> before" \
1010 +" amending the final commit and pushing. This allows for some more " \
1011 +" complex workflows involving local branches with multiple merges." \
1012 +" However, this will result in non-linear history and will allow for" \
1013 +" trivial merge commits with <remoterepo>/<remotebranch> to get pushed. This mode" \
1014 +" should only be used in cases where the rebase mode will not work or " \
1015 +" when it is desired to use a merge commit to integrate changes on a" \
1016 +" branch that you wish be able to easily back out. For sophisticated" \
1017 +" users of git, this may in fact be the preferred mode.",
1018 default=True )
1019
1020 clp.add_option(
1021 "--append-test-results", dest="appendTestResults", action="store_true",
1022 help="Before the final push, amend the most recent local commit by appending a" \
1023 +" summary of the test results. This provides a record of what builds" \
1024 +" and tests were performed in order to test the local changes. This is only " \
1025 +" performed if --push is also set. NOTE: If the same" \
1026 +" local commit is amended more than once, the prior test summary sections will be" \
1027 +" overwritten with the most recent test results from the current run. [default]" )
1028 clp.add_option(
1029 "--no-append-test-results", dest="appendTestResults", action="store_false",
1030 help="Do not amend the last local commit with test results. NOTE: If you have" \
1031 +" uncommitted local changes that you do not want this script to commit then you" \
1032 +" must select this option to avoid this last amending commit. Also, if you are" \
1033 +" pushing commits from a shared branch and don't want to change any of the SHA1s" \
1034 +" for the commits, then you must set this option!",
1035 default=True )
1036
1037 clp.add_option(
1038 "--extra-pull-from", dest="extraPullFrom", type="string", default="",
1039 help="Optional extra git pull(s) to merge in changes from after" \
1040 +" pulling in changes from the tracking branch. The format of this argument is:" \
1041 +" ...,<local-repoi>:<remote-repoi>:<remote-branchi>,... where each pull" \
1042 +" specification gives the name (not the directory) of the local repo <local-repoi>" \
1043 +", the remote repo name <remote-repoi>, and the branch in the remote repo to pull" \
1044 +" <remote-branchi>. If only two semicolons ':' are given then an pull field takes" \
1045 +" the form ...,<remote-repo>:<remote-branch>,... where the remote <remote-name>" \
1046 +" must be defined in all the repos and the branch <remote-branch> must exist" \
1047 +" in all the remote repos. If the <remote-repoi> is empty such as with" \
1048 +" ...,:<remote-repoi>:<remote-branchi>,... then this matches the base git repo." \
1049 +" The extra pull(s) are only done if --pull is also specified. NOTE: when using" \
1050 +" --extra-repos=<repo0>,<repo1>,... the <local-repoi> must be a named repository" \
1051 + " that is present in all of the git repos or it will be an error." )
1052
1053 clp.add_option(
1054 "--allow-no-pull", dest="allowNoPull", action="store_true", default=False,
1055 help="Allowing for there to be no pull performed and still doing the other actions." \
1056 +" This option is useful for testing against local changes without having to" \
1057 +" get the updates from the global repo. However, if you don't pull, you can't" \
1058 +" push your changes to the global repo. WARNING: This does *not* stop a pull" \
1059 +" attempt from being performed by --pull or --do-all!" )
1060
1061 clp.add_option(
1062 "--wipe-clean", dest="wipeClean", action="store_true", default=False,
1063 help="[ACTION] Blow existing build directories and build/test results. The action can be" \
1064 +" performed on its own or with other actions in which case the wipe clean will be" \
1065 +" performed before any other actions. NOTE: This will only wipe clean the builds" \
1066 +" that are specified and will not touch those being ignored (e.g. SERIAL_RELEASE" \
1067 +" will not be removed if --default-builds=MPI_DEBUG is specified)." )
1068
1069 clp.add_option(
1070 "--pull", dest="doPull", action="store_true", default=False,
1071 help="[ACTION] Do the pull from the tracking branch and optionally also" \
1072 +" merge in changes from the repo pointed to by --extra-pull-from.")
1073
1074 clp.add_option(
1075 "--configure", dest="doConfigure", action="store_true", default=False,
1076 help="[ACTION] Do the configure step." )
1077
1078 clp.add_option(
1079 "--build", dest="doBuild", action="store_true", default=False,
1080 help="[ACTION] Do the build step." )
1081
1082 clp.add_option(
1083 "--test", dest="doTest", action="store_true", default=False,
1084 help="[ACTION] Do the running of the enabled tests." )
1085
1086 clp.add_option(
1087 "--local-do-all", dest="localDoAll", action="store_true", default=False,
1088 help="[AGGR ACTION] Do configure, build, and test with no pull (same as setting" \
1089 +" --allow-no-pull ---configure --build --test)." \
1090 +" This is the same as --do-all except it does not do --pull and also allows for no pull." )
1091
1092 clp.add_option(
1093 "--do-all", dest="doAll", action="store_true", default=False,
1094 help="[AGGR ACTION] Do update, configure, build, and test (same as --pull --configure" \
1095 +" --build --test). NOTE: This will do a --pull regardless if --allow-no-pull" \
1096 +" is set or not. To avoid the pull, use --local-do-all." )
1097
1098 clp.add_option(
1099 "--push", dest="doPush", action="store_true", default=False,
1100 help="[ACTION] Push the committed changes in the local repo into to remote repo" \
1101 +" pointed to by the tracking branch." )
1102
1103 clp.add_option(
1104 "--execute-on-ready-to-push", dest="executeOnReadyToPush", type="string", default="",
1105 help="[ACTION] A command to execute on successful execution and 'READY TO PUSH'" \
1106 +" status from this script. This can be used to do a remote SSH invocation to a" \
1107 +" remote machine to do a remote pull/test/push after this machine finishes." )
1108
1109 (options, args) = clp.parse_args(args=commandLineArgs)
1110
1111 # NOTE: Above, in the pairs of boolean options, the *last* add_option(...)
1112 # takes effect! That is why the commands are ordered the way they are!
1113
1114
1115 #
1116 # Echo the command-line
1117 #
1118
1119 print("")
1120 print("**************************************************************************")
1121 print("Script: checkin-test.py \\")
1122
1123 print(" --src-dir='" + options.srcDir+"' \\")
1124 print(" --default-builds='" + options.defaultBuilds + "' \\")
1125 print(" --extra-repos-file='"+options.extraReposFile+"' \\")
1126 print(" --extra-repos-type='"+options.extraReposType+"' \\")
1127 print(" --extra-repos='"+options.extraRepos+"' \\")
1128 if options.ignoreMissingExtraRepos:
1129 print(" --ignore-missing-extra-repos \\")
1130 else:
1131 print(" --require-extra-repos-exist \\")
1132 if options.skipDepsUpdate:
1133 print(" --skip-deps-update \\")
1134 print(" --enable-packages='"+options.enablePackages+"' \\")
1135 print(" --enable-extra-packages='"+options.enableExtraPackages+"' \\")
1136 print(" --disable-packages='"+options.disablePackages+"' \\")
1137 print(" --enable-all-packages='"+options.enableAllPackages+"'\\")
1138 if options.enableFwdPackages:
1139 print(" --enable-fwd-packages \\")
1140 else:
1141 print(" --no-enable-fwd-packages \\")
1142 if options.abortGracefullyIfNoChangesPulled:
1143 print(" --abort-gracefully-if-no-changes-pulled \\")
1144 else:
1145 print(" --continue-if-no-updates \\")
1146 if options.abortGracefullyIfNoChangesToPush:
1147 print(" --abort-gracefully-if-no-changes-to-push \\")
1148 else:
1149 print(" --continue-if-no-changes-to-push \\")
1150 if options.abortGracefullyIfNoEnables:
1151 print(" --abort-gracefully-if-no-enables \\")
1152 else:
1153 print(" --continue-if-no-enables \\")
1154 print(" --extra-cmake-options='"+options.extraCmakeOptions+"' \\")
1155 print(" --test-categories='"+options.testCategories+"' \\")
1156 if options.overallNumProcs:
1157 print(" -j"+options.overallNumProcs+" \\")
1158 if options.useNinja:
1159 print(" --use-ninja \\")
1160 else:
1161 print(" --use-makefiles \\")
1162 print(" --make-options='"+options.makeOptions+"' \\")
1163 print(" --ctest-options='"+options.ctestOptions+"' \\")
1164 print(" --ctest-timeout="+str(options.ctestTimeOut)+" \\")
1165 if options.showAllTests:
1166 print(" --show-all-tests \\")
1167 else:
1168 print(" --no-show-all-tests \\")
1169 if options.withoutDefaultBuilds:
1170 print(" --without-default-builds \\")
1171 print(" --st-extra-builds='"+options.stExtraBuilds+"' \\")
1172 print(" --extra-builds='"+options.extraBuilds+"' \\")
1173 print(" --log-file='"+options.logFile+"' \\")
1174 print(" --send-email-to='"+options.sendEmailTo+"' \\")
1175 if options.skipCaseSendEmail:
1176 print(" --skip-case-send-email \\")
1177 else:
1178 print(" --skip-case-no-email \\")
1179 print(" --send-build-case-email="+str(options.sendBuildCaseEmail)+" \\")
1180 if not options.sendEmailOnlyOnFailure:
1181 print(" --send-email-for-all \\")
1182 else:
1183 print(" --send-email-only-on-failure \\ ")
1184 print(" --send-email-to-on-push='"+options.sendEmailToOnPush+"' \\")
1185 if options.forcePush:
1186 print(" --force-push \\")
1187 else:
1188 print(" --no-force-push \\")
1189 if options.doPushReadinessCheck:
1190 print(" --do-push-readiness-check \\")
1191 else:
1192 print(" --skip-push-readiness-check \\")
1193 if options.rebase:
1194 print(" --rebase \\")
1195 else:
1196 print(" --no-rebase \\")
1197 if options.appendTestResults:
1198 print(" --append-test-results \\")
1199 else:
1200 print(" --no-append-test-results \\")
1201 if options.extraPullFrom:
1202 print(" --extra-pull-from='"+options.extraPullFrom+"' \\")
1203 if options.allowNoPull:
1204 print(" --allow-no-pull \\")
1205 if options.wipeClean:
1206 print(" --wipe-clean \\")
1207 if options.doPull:
1208 print(" --pull \\")
1209 if options.doConfigure:
1210 print(" --configure \\")
1211 if options.doBuild:
1212 print(" --build \\")
1213 if options.doTest:
1214 print(" --test \\")
1215 if options.localDoAll:
1216 print(" --local-do-all \\")
1217 if options.doAll:
1218 print(" --do-all \\")
1219 if options.doPush:
1220 print(" --push \\")
1221 if options.executeOnReadyToPush:
1222 print(" --execute-on-ready-to-push=("+options.executeOnReadyToPush+") \\")
1223 if options.ssExtraBuilds:
1224 print(" --ss-extra-builds='"+options.ssExtraBuilds+"' \\")
1225 print("\nWARNING: --ss-extra-builds is deprecated! Use --st-extra-builds instead!")
1226 if options.stExtraBuilds:
1227 print("ERROR: Can't set deprecated --ss-extra-builds and --st-extra-builds together!")
1228 sys.exit(3)
1229 options.stExtraBuilds = options.ssExtraBuilds
1230
1231
1232 #
1233 # Check and adjust the input arguments
1234 #
1235
1236 if not os.path.isabs(options.srcDir):
1237 options.srcDir = os.path.abspath(options.srcDir)
1238
1239 if options.doAll and options.localDoAll:
1240 print("\nError, you can not use --do-all and --local-do-all together! Use on or the other!")
1241 sys.exit(1)
1242
1243 if options.doAll and options.allowNoPull:
1244 print("\nError, you can not use --do-all and --allow-no-pull together! (see the" \
1245 " documentation for the --do-all, --local-do-all, and --allow-no-pull arguments.)")
1246 sys.exit(2)
1247
1248 if options.extraPullFrom:
1249 for extraPullFromArg in options.extraPullFrom.split(","):
1250 # Will validate form of argument
1251 getLocalRepoRemoteRepoAndBranchFromExtraPullArg(extraPullFromArg)
1252
1253
1254 #
1255 # Execute the checkin test guts
1256 #
1257
1258 import time
1259
1260 if not options.showDefaults:
1261
1262 print("\nStarting time:", getCmndOutput("date",True))
1263
1264 tribitsDir = os.path.abspath(getCompleteFileDirname(__file__)+"/..") # TriBITS dir!
1265
1266 t1 = time.time()
1267 success = checkinTest(tribitsDir, options, configuration)
1268 t2 = time.time()
1269 print("\nTotal time for checkin-test.py =", formatMinutesStr((t2-t1)/60.0))
1270
1271 print("\nFinal time:", getCmndOutput("date",True))
1272
1273 if options.ssExtraBuilds:
1274 print("\n***")
1275 print("*** FINAL WARNING: stop using deprecated --ss-extra-builds! Use --st-extra-builds instead!")
1276 print("***")
1277
1278 if success:
1279 print("\nREQUESTED ACTIONS: PASSED\n")
1280 return True
1281 else:
1282 print("\nREQUESTED ACTIONS: FAILED\n")
1283 return False
1284 else:
1285 return True
1286
1287
1288 def getConfigurationSearchPaths():
1289 """
1290 Gets a list of paths to search for the configuration. If this file
1291 was invoked from a symlink, look in the directory that contains the
1292 symlink. The returned list will always contain at least one element.
1293 """
1294 result = []
1295
1296 # First, look for the checkin-test.py file's base directory path. It is
1297 # common practice to symbolically link the checkin-test.py script into the
1298 # project's base source directory. NOTE: Don't use realpath here! We don't
1299 # want to follow symbolic links!
1300 result.append(os.path.dirname(os.path.abspath(__file__)))
1301
1302 # Second, look for the configuration file assuming the checkin-test.py
1303 # script is run out of the standard snapshotted tribits directory
1304 # <project-root>/cmake/tribits/ci_support
1305 result.append(os.path.join(thisFileRealAbsBasePath, '..', '..', '..'))
1306
1307 return result
1308
1309
1310 def loadConfigurationFile(filepath):
1311 if os.path.exists(filepath):
1312 sys_path_old = sys.path
1313 try:
1314 modulePath = os.path.dirname(filepath)
1315 moduleFile = os.path.basename(filepath)
1316 moduleName, extension = os.path.splitext(moduleFile)
1317 sys.path = [modulePath] + sys_path_old
1318 try:
1319 if debugDump:
1320 print("\nLoading project configuration from %s..." % filepath)
1321 print("\nsys.path =", sys.path)
1322 configuration = __import__(moduleName).configuration
1323 if debugDump:
1324 print("\nSetting the default --src-dir='"+modulePath+"'")
1325 configuration.get("defaults").update({"--src-dir" : modulePath})
1326 return configuration
1327 except Exception as e:
1328 print(e)
1329 raise e
1330 finally:
1331 sys.path = sys_path_old
1332 if debugDump:
1333 print("\nsys.path =", sys.path)
1334 else:
1335 raise Exception('The file %s does not exist.' % filepath)
1336
1337
1338 def getLocalCmndLineArgs():
1339 localDefaults = []
1340 checkinTestDir = os.getcwd()
1341 localProjectDefaultsBaseName = "local-checkin-test-defaults"
1342 localProjectDefaultsFile = checkinTestDir+"/"+localProjectDefaultsBaseName+".py"
1343 if os.path.exists(localProjectDefaultsFile):
1344 sys_path_old = sys.path
1345 try:
1346 sys.path = [checkinTestDir] + sys_path_old
1347 if debugDump:
1348 print("\nLoading local default command-line args from "+localProjectDefaultsFile+"...")
1349 print("\nsys.path =", sys.path)
1350 localDefaults = __import__(localProjectDefaultsBaseName).defaults
1351 finally:
1352 sys.path = sys_path_old
1353 if debugDump:
1354 print("\nsys.path =", sys.path)
1355 return localDefaults
1356
1357
1358 def locateAndLoadConfiguration(path_hints = []):
1359 """
1360 Locate and load a module called checkin_test_project_configuration.py. The
1361 path_hints argument can be used to provide location hints at which to locate
1362 the file. Returns a configuration dictionary. If the module is not found,
1363 this dictionary will be empty.
1364 """
1365 for path in path_hints:
1366 candidate = os.path.join(path, "project-checkin-test-config.py")
1367 if debugDump: print("\nLooking for candidate configuration file '%s'" % candidate)
1368 if os.path.exists(candidate):
1369 return loadConfigurationFile(candidate)
1370 return {}
1371
1372
1373 #
1374 # Main
1375 #
1376
1377 def main(cmndLineArgs):
1378
1379 # See if the help option is set or not
1380 helpOpt = len( set(cmndLineArgs) & set(("--help", "-h")) ) > 0
1381
1382 # See if --show-defaults was set or not
1383 showDefaultsOpt = len( set(cmndLineArgs) & set(("--show-defaults", "dummy")) ) > 0
1384
1385
1386 if (not helpOpt) and (not showDefaultsOpt):
1387 # Get the name of the log file from the input arguments
1388 logFileName = "checkin-test.out"
1389 for cmndLineArg in cmndLineArgs:
1390 cmndLineSplit = cmndLineArg.split("=")
1391 if cmndLineSplit[0].strip() == "--log-file":
1392 logFileName = cmndLineSplit[1].strip()
1393 logFile = open(logFileName, "w", buffering=1) # 1 == line-by-line buffering
1394 # NOTE: Above, we need to set biffering=1 to make sure that each line that
1395 # gets written is written out the file. The is critical so that the user
1396 # can to a `tail -f <log-file>` to see what is going one.
1397 else:
1398 logFile = None
1399
1400 # There are a lot of print(statements in the implementation. It's
1401 # easier to reset sys.stdout and sys.stderr to a TeeOutput object
1402 # than to replace them.
1403 teeOutput = TeeOutput(logFile)
1404 originalStdout = sys.stdout
1405 originalStderr = sys.stderr
1406 try:
1407 sys.stdout = teeOutput
1408 sys.stderr = teeOutput
1409 try:
1410 # See if there is a configuration file override.
1411 configuration = None
1412 for arg in cmndLineArgs:
1413 if arg.startswith('--project-configuration='):
1414 print("Found configuration override %s..." % arg)
1415 configuration = loadConfigurationFile(arg.split('=')[1])
1416 elif not configuration and arg.startswith('--src-dir='):
1417 configuration = locateAndLoadConfiguration([arg.split('=')[1]])
1418 if not configuration:
1419 configuration = locateAndLoadConfiguration(getConfigurationSearchPaths())
1420 localCmndLineArgs = getLocalCmndLineArgs()
1421 if localCmndLineArgs:
1422 if debugDump:
1423 print("\ncmndLineArgs =", cmndLineArgs)
1424 print("\nlocalCmndLineArgs =", localCmndLineArgs)
1425 cmndLineArgs = localCmndLineArgs + cmndLineArgs
1426 if debugDump:
1427 print("\ncmndLineArgs =", cmndLineArgs)
1428 if debugDump:
1429 print("\nConfiguration loaded from configuration file =", configuration)
1430 success = runProjectTestsWithCommandLineArgs(cmndLineArgs, configuration)
1431 except SystemExit as e:
1432 # In Python 2.6, SystemExit inherits Exception, but for proper exit
1433 # behavior the SystemExit exception must propagate all the way to the top
1434 # of the call stack. It cannot get handled by the catch Exception below.
1435 raise e
1436 except Exception as e:
1437 success = False
1438 traceback.print_exc(file=teeOutput)
1439 finally:
1440 # Close the log file
1441 if logFile: logFile.close()
1442 # Reset stdout and stderr
1443 sys.stdout = originalStdout
1444 sys.stderr = originalStderr
1445
1446 if success:
1447 return 0
1448 else:
1449 return 1
1450
1451 if __name__ == '__main__':
1452 sys.exit(main(sys.argv[1:]))