TestingBuilds.md

   1 The installation page has a simple test process which will work most of the time to get your system up and running.  This page has more detail about running the test process to achieve various things.
   2
   3 The base script which handles everything is the run_build.pl script.  The commandline options are:
   4
   5     $ ./run_build.pl --help
   6
   7     usage: ./run_build.pl [options] [branch]
   8
   9      where options are one or more of:
  10
  11       --nosend                  = don't send results
  12       --nostatus                = don't set status files
  13       --force                   = force a build run (ignore status files)
  14       --from-source=/path       = use source in path, not from SCM
  15       or
  16       --from-source-clean=/path = same as --from-source, run make distclean first
  17       --config=/path/to/file    = alternative location for config file
  18       --keepall                 = keep directories if an error occurs
  19       --verbose[=n]             = verbosity (default 1) 2 or more = huge output.
  20       --quiet                   = suppress normal error message
  21       --test                    = short for --nosend --nostatus --verbose --force
  22       --skip-steps=list         = skip certain steps
  23       --only-steps=list         = only do certain steps, not allowed with skip-steps
  24                                   lists can be comma, colon, or space separated
  25
  26     Default branch is HEAD. Usually only the --config option should be necessary.
  27
  28 ### Valid Stages:
  29 * configure
  30 * make
  31 * make-doc  (optional, off by default)
  32 * test      (optional, off by default)
  33
  34 In each of the following sample command lines, remember that `--test` will force all steps and will not locally store the state of the git checkout nor the state of each of stage, nor will it submit the results to the server.
  35
  36 1. Most of the time, you probably just want to enable a feature and test if the build process changes.  In that case, this command is likely all that you'll want:
  37 `./run_build.pl --test --verbose=2 --only-steps=configure,make`
  38
  39 2. Test mode, run just configure and make steps, and keep the directories:
  40 `./run_build.pl --test --only-steps configure,make --keepall`
  41
  42 3. Test mode, debug mode, run just configure and make steps:
  43 `./run_build.pl --test --only-steps configure,make --verbose=2`
  44
  45 4. Debug mode, only run configure and make if there is a new commit, submit results to server:
  46 `./run_build.pl --only-steps configure,make --verbose=2`
  47
  48 5. Run all steps, only if there is a new commit, configured to also do make_test, but limit the range of tests from 1 to 9:
  49 `./run_build.pl --override range_test_num='1 9'`
  50
  51 6. Just build docs, don't submit results (configure builds the *Local/Makefile*, which is required for doc building) :
  52 `./run_build.pl --force --only-steps=configure,make-doc --nosend`
  53
  54 7. Just build docs, equivalent command:
  55 `./run_build.pl --test --only-steps=configure,make-doc`
  56
  57 8. Just build docs, but allow it to submit results (not advised since you aren't building the actual binary) :
  58 `./run_build.pl --force --only-steps=configure,make-doc`
  59
  60
  61 ### Extreme test debugging
  62 Sometimes you need to figure out why one test is failing.  To see exactly what is happening, you can create a temporary build, don't delete it, and then manually run the test in a debug mode.  In the following example, I'll assume that I'm wanting to find why test 433 is failing
  63
  64     PATH="$PATH:/sbin" ./run_build.pl --test --verbose=2 --force --only-steps=configure,make,test \
  65       --override range_num_tests='1 1' --keepall
  66
  67 The above will create a subdirectory of the format _exim.$PID_ (of the script running the build farm).  In the example above, the git checkout of the exim sources was in `$HOME/buildfarm/HEAD/exim.4689/`, so we change into the test directory and manually instantiate the runtest script, specifying which test we want it to run.
  68
  69     ./runtest $HOME/buildfarm/HEAD/exim.4689/src/build-Linux-i386/exim -DEBUG 433 433
  70
  71 It will print out copious debug output and you can hopefully find the problem based on that output.