nightly/README.txt

   1 INTRO
   2 -----
   3 This directory (nightly/) contains a simple, automatic build-and-test
   4 system for Valgrind, intended to be run nightly by cron or a similar
   5 program.
   6
   7
   8 BASIC OPERATIONS
   9 ----------------
  10 When run, the system clones and checks out two trees: one from 24 hours ago
  11 and the HEAD from now.  ("24 hours ago" and "now" are determined when
  12 the script starts running, so if any commits happen while the tests are
  13 running they will not be tested.)
  14
  15 If the two trees are different (i.e. there have been commits in the past 24
  16 hours, either to the master or a branch) it builds ("make"), installs ("make
  17 install") and runs the regression tests ("make regtest") in both, and
  18 compares the results.  Note that the "make install" isn't necessary in order
  19 to run the tests because the regression tests use the code built (with
  20 "make") within the tree, but it's worth doing because it tests that "make
  21 install" isn't totally broken.  After checking both trees, it emails a
  22 summary of the results to a recipient.  All this typically takes something
  23 like 30 minutes.
  24
  25 If the two trees are identical, the tests are not run and no results are
  26 emailed.  This avoids spamming people with uninteresting results emails when
  27 no commits have happened recently.
  28
  29 The requirements for the machine running the nightly tests are the same as
  30 for running the regression tests (see README_DEVELOPERS) plus GNU coreutils
  31 and the ability to send e-mail. The mail transport agent used depends on the
  32 platform and is decribed in step (4) below.
  33
  34
  35 SETTING UP
  36 ----------
  37 To set up nightly testing for a machine, do the following.
  38
  39 (1) Clone a shallow copy from the repository, eg:
  40
  41         git clone --depth 1 https://sourceware.org/git/valgrind.git/ $DIR
  42
  43     where $DIR is the name of the directory you want it to be in.
  44     You'll probably want to include "nightly" in the directory name.
  45
  46     Note that this doesn't clone the whole repo history, just the latest
  47     revision of everything in the repository. Under $DIR, only directory
  48     "nightly" is of interest to us - the rest is ignored. In other words: the
  49     testing script clones and checks out new trees (within $DIR/nightly) and
  50     tests them independently.
  51
  52 (2) Choose a tag that identifies the test results.  This is usually the
  53     machine name.  We'll call it $TAG in what follows.
  54
  55 (3) Create a configuration file $DIR/nightly/conf/$TAG.conf. It is sourced
  56     by the 'nightly' script, and can define any or all of the following
  57     environment variables. (In most cases, only ABT_DETAILS is needed.)
  58
  59     - ABT_DETAILS: describes the machine in more detail, eg. the OS.  The
  60       default is empty, but you should define it.  An example:
  61
  62         export ABT_DETAILS="Ubuntu 9.04, Intel x86-64"
  63
  64       You could also use some invocation of 'uname' or something similar
  65       to generate this string.  Eg. on Ubuntu Linux this works nicely:
  66
  67         export ABT_DETAILS="`cat /etc/issue.net`, `uname -m`"
  68
  69       And on Mac OS X this works nicely:
  70
  71         export ABT_DETAILS=`uname -mrs`
  72
  73       The advantage of doing it like this is that if you update the OS on
  74       the test machine you won't have to update ABT_DETAILS manually.
  75
  76     - ABT_CONFIGURE_OPTIONS: gives extra configure options.  The default is
  77       empty.
  78
  79     - ABT_EVAL: if provided, it must be the name of a shell script that
  80       executes the shell command $1 with arguments $2 .. ${$#}.  Allows to
  81       compile and run the Valgrind regression tests on another system than
  82       the system the 'nightly' script runs on.  It is assumed that the remote
  83       system shares the local filesystem tree through e.g. NFS.  It is the
  84       responsibility of the shell script to set the remote working directory
  85       such that it matches the local current directory ($PWD).
  86
  87     - ABT_RUN_REGTEST: if provided, it must be the name of an argumentless
  88       shell function (also specified in the $TAG.conf file) that will be used
  89       to run the tests.  If not specified, the usual "make regtest" will be
  90       used.
  91
  92     - ABT_JOBS: allows parallel builds -- it's passed as the argument to
  93       "make -j" when building Valgrind and the tests.  The default is 1.
  94
  95     - ABT_PERF: unset or set to "" mean 'do not run perf tests' (default value)
  96                 set to "--vg=../valgrind-new" (run perf tests for new tree)
  97                 set to "--vg=../valgrind-new --vg=../valgrind-old"
  98                 (run  perf tests for "new" and for "24 hours ago",
  99                  to compare the performances between the 2 trees).
 100
 101     - ABT_PERF_TOOLS: --tools=.... option of perf/vg_perf.
 102       (default value: all non experimental tools)
 103
 104     - ABT_PERF_REPS: --reps=... option of perf/vg_perf
 105       (default value: --reps=3)
 106
 107     Note that the appropriate syntax to use in this file will depend on the
 108     shell from which the $DIR/nightly/bin/nightly script is run (which in turn
 109     may depend on what shell is used by cron or any similar program).
 110
 111 (4) Create a mailer script $DIR/nightly/conf/$TAG.sendmail. It must be
 112     executable. It's used to send email results to the desired recipient (e.g.
 113     valgrind-developers@lists.sourceforge.net). It must handle three command
 114     line arguments.
 115
 116     - The first argument is the email subject line.  It contains
 117       $ABT_DETAILS plus some other stuff.
 118
 119     - The second argument is the name of the file containing the email's
 120       body (which shows the tests that failed, and the differences between now
 121       and 24 hours ago).
 122
 123     - The third is the name of the file containing all the diffs from
 124       failing tests.  Depending on the test results you get, you could
 125       inline this file into the email body, or attach it, or compress and
 126       attach it, or even omit it.  The right choice depends on how many
 127       failures you typically get -- if you get few failures, inlining the
 128       results make them easier to read;  if you get many failures,
 129       compressing might be a good idea to minimise the size of the emails.
 130
 131     The best way to do this depends on how mail is set up on your machine.
 132     You might be able to use /usr/bin/mail, or you might need something more
 133     elaborate like using Mutt to send mail via an external account.
 134
 135     At first, you should probably just send emails to yourself for testing
 136     purposes.  After it's working, then sending it to others might be
 137     appropriate.
 138
 139 (5) To run the tests, execute:
 140
 141        $DIR/nightly/bin/nightly $DIR/nightly $TAG
 142
 143     You probably want to put this command into a cron file or equivalent
 144     so it is run regularly (preferably every night).  Actually, it's
 145     probably better to put that command inside a script, and run the script
 146     from cron, rather than running $DIR/nightly/bin/nightly directly. That way
 147     you can put any other configuration stuff that's necessary inside the
 148     script (e.g. make sure that programs used by the mailer script are in
 149     your PATH).
 150
 151
 152 OUTPUT FILES
 153 ------------
 154 If the tests are run, the following files are produced:
 155
 156 - $DIR/nightly/old.verbose and $DIR/nightly/new.verbose contain full output of
 157   the whole process for each of the two trees.
 158
 159 - $DIR/nightly/old.short and $DIR/nightly/new.short contain summary output of
 160   the process for each of the two trees. The diff between these two files goes
 161   in $DIR/nightly/diff.short.
 162
 163 - $DIR/nighlty/final contains the overall summary, constructed from
 164   $DIR/nightly/old.short, $DIR/nightly/new.short, $DIR/nightly/diff.short and
 165   some other bits and pieces. (The name of this file is what's passed as the
 166   second argument to $DIR/nightly/conf/$TAG.sendmail.)
 167
 168 - $DIR/nightly/diffs holds the diffs from all the failing tests in the newer
 169   tree, concatenated together; the diff from each failure is truncated at 100
 170   lines to minimise possible size blow-outs. (The name of this file is
 171   what's passed as the third argument to $DIR/nightly/conf/$TAG.sendmail.)
 172
 173 - $DIR/nightly/sendmail.log contains the output (stdout and stderr) from
 174   $DIR/nightly/conf/$TAG.sendmail goes in $DIR/nightly/sendmail.log.
 175
 176 - $DIR/nightly/valgrind-old/ and $DIR/nightly/valgrind-new/ contain the tested
 177   trees (and $DIR/nightly/valgrind-old/Inst/ and $DIR/nightly/valgrind-new/Inst/
 178   contain the installed code).
 179
 180 If the tests aren't run, the following file is produced:
 181
 182 - $DIR/nightly/unchanged.log is created only if no tests were run because the
 183   two trees were identical. It will contain a short explanatory message.
 184
 185 Each time the tests are run, all files from previous runs are deleted.
 186
 187
 188 TROUBLESHOOTING
 189 ---------------
 190 If something goes wrong, looking at the output files can be useful.  For
 191 example, if no email was sent but you expected one, check sendmail.log to
 192 see if the mailer script had a problem.  Or check if unchanged.log exists.
 193
 194 Occasionally the git server isn't available when the tests runs, for either
 195 or both trees.  When this happens the email will be sent but it won't be
 196 very informative.  Usually it's just a temporary server problem and it'll
 197 run fine the next time without you having to do anything.
 198
 199 Note that the test suite is imperfect:
 200 - There are very few machines where all tests pass;  that's why the old/new
 201   diff is produced.  Some of the tests may not be as portable as intended.
 202 - Some tests are non-deterministic, and so may pass one day and fail the
 203   next.
 204
 205 Improving the test suite to avoid these problems is a long-term goal but it
 206 isn't easy.
 207
 208
 209 MAINTENANCE
 210 -----------
 211 The scripts in the nightly/ directory occasionally get updated.  If that
 212 happens, you can just "git pull" within $DIR to get the updated versions,
 213 which will then be used the next time the tests run.  (It's possible that
 214 the scripts will be changed in a way that requires changes to the files in
 215 $DIR/nightly/conf/, but we try to avoid this.)
 216
 217 If you want such updates to happen automatically, you could write a script
 218 that does all the steps in SETTING UP above, and instead run that script
 219 from cron.