Sisyphus/Usage
Although Sisyphus contains a number of different scripts, only builder.sh and tester.sh are intended to be used directly. Normally, builder.sh and tester.sh's complexity is hidden by a wrapper script such as the JavaScript Tests' runtests.sh which handles both creating builds and running tests.
Contents
builder.sh
builder.sh handles the task of cleaning, checking out and building the executable programs to be tested. Typically, the Sisyphus framework will call builder.sh when it needs a build, however the script is useful in its own right when all you need to do is generate a set of builds.
usage:
builder.sh -p products -b branches -B buildcommands -T buildtypes [-e extra] [-d datafiles] [-v]
variable description
=============== ===========================================================
-p products required. one or more of js firefox thunderbird
-b branches required. one or more of 1.8.0 1.8.1 1.9.0 1.9.1
-B buildcommands required. one or more of clean checkout build
-T buildtypes required. one or more of opt debug
-e extra optional. extra qualifier to pick build tree and mozconfig.
-d datafiles optional. one or more filenames of files containing
environment variable definitions to be included.
-v optional. verbose - copies log file output to stdout.
note that the environment variables should have the same names as in the
"variable" column.
Using builder.sh with command-line arguments
For example, to checkout and build opt and debug builds of Firefox for the 1.8.1 and 1.9.0 branches in your "test" trees, you could call builder.sh as:
builder.sh -p "firefox" -b "1.8.1 1.9.0" -e test -T "opt debug" -B "checkout build"
builder.sh will checkout and build Firefox using the appropriate mozconfig files located in /work/mozilla/builds/1.8.1-test and /work/mozilla/builds/1.9.0-test as described in Create Build Directory for branches 1.8.1, 1.9.0 in the trees /work/mozilla/builds/1.8.1-test/mozilla and /work/mozilla/builds/1.9.0-test/mozilla while writing the log file names to stdout.
log: /work/mozilla/mozilla.com/test.mozilla.com/www/results/2008-07-09-11-37-27-0400,firefox,1.8.1-test,,linux,sophie.bclary.com,checkout.log log: /work/mozilla/mozilla.com/test.mozilla.com/www/results/2008-07-09-11-37-43-0400,firefox,1.9.0-test,,linux,sophie.bclary.com,checkout.log log: /work/mozilla/mozilla.com/test.mozilla.com/www/results/2008-07-09-11-37-59-0400,firefox,1.8.1-test,opt,linux,sophie.bclary.com,build.log log: /work/mozilla/mozilla.com/test.mozilla.com/www/results/2008-07-09-11-38-15-0400,firefox,1.8.1-test,debug,linux,sophie.bclary.com,build.log log: /work/mozilla/mozilla.com/test.mozilla.com/www/results/2008-07-09-11-38-22-0400,firefox,1.9.0-test,opt,linux,sophie.bclary.com,build.log log: /work/mozilla/mozilla.com/test.mozilla.com/www/results/2008-07-09-11-38-41-0400,firefox,1.9.0-test,debug,linux,sophie.bclary.com,build.log
The log file names follow a definite template:
2008-07-09-11-38-41-0400,firefox,1.9.0-test,debug,linux,sophie.bclary.com,build.log
---- -- -- -- -- ------- ------- ----- ---- ----- ----- ----------------- -----
U Y M D H M S T O P B E B T O S M N C
T e o a o i e i f r r x u y p y a a o
C a n y u n c m f o a t i p e s c m m
r t r u o e s d n r l e r t h e m
h t n z e u c a d a e i a
e d o t c h t m n n
s s n t i e d
e n
g
If an error occurs during any step, the message FATAL ERROR is written to the log as well as stderr and processing will stop.
Using builder.sh with "datafiles"
Sisyphus "datafiles" are essentially bash scripts located in $TEST_DIR/data which can be sourced into a running script to provide stored configurations of environment variables and command line arguments. This not only can help in simplifying passing arguments among sisyphus' many component scripts, it can also be used to provide arbitrary environment variable definitions such as TEST_MOZILLA_HG for default mercurial repositories.
For example, the following reproduces the checkout and build of opt and debug Firefox builds in the "test" trees.
builder.sh -d "firefox,1.8.1-test,opt.data firefox,1.8.1-test,debug.data firefox,1.9.0-test,opt.data firefox,1.9.0-test,debug.data"
where $TEST_DIR/data/firefox,1.8.1,opt.data would contain (at least)
product=firefox branch=1.8.1 extra=test buildtype=opt
and so on.
tester.sh
tester.sh is a dispatcher-like script which is designed to setup a test environment, download and install or build, create profiles, initialize preferences, install extensions or plugins,...) and make a test run for each of the specified datafile combinations. Although it can be called directly, it is better and more commonly used in a wrapper script. See JavaScript Tests' runtests.sh for an example.
usage:
tester.sh -t testscript [-v ] datalist1 [datalist2 [datalist3 [datalist4]]]
variable description
=============== ===========================================================
-t testscript required. quoted test script with required arguments.
-v optional. verbose - copies log file output to stdout.
executes the testscript for each input data file in
/work/mozilla/mozilla.com/test.mozilla.com/www/data/{item1},{item2},{item3},{item4}.data
constructed from each combination of the input parameters.
where item1 belongs to datalist1, etc.
Environment Variables
- BUILDDIR=${BUILDDIR:-/work/mozilla/builds}
The location of the Sisyphus build directory
- DEBUG
When non-null, causes debugging messages to be output by the various scripts.
- MOZ_CRASHREPORTER_NO_REPORT=${MOZ_CRASHREPORTER_NO_REPORT:-1}
Controls whether crash reports are sent in Gecko 1.9.0 and later. This only has an effect for nightly builds which are downloaded and installed.
- MOZ_GDB_SLEEP=${MOZ_GDB_SLEEP:-10}
Controls the time in seconds a build will wait after crashing before terminating.
- TEST_HTTP=${TEST_HTTP:-test.mozilla.com}
The web server used in browser tests.
- TEST_MOZILLA_HG_LOCAL=${TEST_MOZILLA_HG_LOCAL:-$BUILDDIR/hg.mozilla.org/`basename $TEST_MOZILLA_HG`}
The path to the local clones of the mercurial repositories used in builds.
- TEST_MOZILLA_HG=${TEST_MOZILLA_HG:-http://hg.mozilla.org/}
The default mercurial repository.
- TEST_STARTUP_TIMEOUT=${TEST_STARTUP_TIMEOUT:-30}
The time in seconds that Sisyphus will wait for the browser to complete loading an initialization page.
- TEST_STARTUP_TRIES=${TEST_STARTUP_TRIES:-3}
The number of times Sisyphus will attempt to load the Spider extension in the browser before giving up.
- XPCOM_DEBUG_BREAK=${XPCOM_DEBUG_BREAK:-warn}
Contols whether debug dialogs, stacks or warnings are generated when an assertion occurs in the browser. If set to stack, and if fix-linux-stack.pl, fix-macosx-stack.pl are found on the PATH, they will be used to post process the logs to create Stacks containing symbols from the tested build.
Back to Sisyphus
