View source for Sisyphus/Usage

Although Sisyphus contains a number of different [[Sisyphus - Script Reference|scripts]], only [[Sisyphus - Script Reference#builder.sh|builder.sh]] and [[Sisyphus - Script Reference#tester.sh|tester.sh]] are intended to be used directly. Normally, <code>builder.sh</code> and <code>tester.sh</code>'s complexity is hidden by a wrapper script such as the JavaScript Tests' <code>[[Sisyphus - JavaScript Tests#runtests.sh|runtests.sh]]</code> which handles both creating builds and running tests.

= builder.sh =

<code>builder.sh</code> handles the task of cleaning, checking out and building the executable programs to be tested. Typically, the Sisyphus framework will call <code>builder.sh</code> 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.

<pre><nowiki>
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.
</nowiki></pre>

== 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:

<pre>
builder.sh -p "firefox" -b "1.8.1 1.9.0" -e test -T "opt debug" -B "checkout build" 
</pre>

<code>builder.sh</code> 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 [[Sisyphus - Installation#Create Build Directory|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. 

<pre>
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
</pre>

The log file names follow a definite template:

<pre>
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
</pre>

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.

<pre>
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"
</pre>

where <code>$TEST_DIR/data/firefox,1.8.1,opt.data</code> would contain (at least)

<pre>
product=firefox
branch=1.8.1
extra=test
buildtype=opt
</pre>

and so on.

= tester.sh =

<code>[[Sisyphus - Script Reference#tester.sh|tester.sh]]</code> 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' <code>[[Sisyphus - JavaScript Tests#runtests.sh|runtests.sh]]</code> for an example.

<pre><nowiki>
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.
</nowiki></pre>

= 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 <code>stack</code>, and if <code>fix-linux-stack.pl</code>, <code>fix-macosx-stack.pl</code> are found on the <code>PATH</code>, they will be used to post process the logs to create Stacks containing symbols from the tested build.

Back to [[Sisyphus]]

[[Category:Sisyphus]]