Latest revision as of 23:11, 20 January 2011

Disclaimer! I tested the tinderbox scripts that are described on this page only with W32-tcsh but they should work with any *NIX like system. They are to be considered of beta quality only. Patches are very much appreciated.

What is tinderbox

In essence tinderbox collects build logs and presents the logs and the result it in a nice, clear and concise way It is very easy to tell whether build complete successfully or not and whether the results are still valid (there could have been changes to the sourcecode in the meantime). It collects the logs from separate and de-coupled build machines. Tinderbox has a few elaborations over the most simple 'status' web-page, inasmuch that it integrates with bonsai - to correlate builds against commits, and it has some nice built in error-parsers to allow huge build logs to be condensed to just a few (possible) tricky sections.

Our tinderbox uses the Tinderbox 2 from the mozilla project plus some small cosmetic changes. Additional documentation can be found there.

Setting up a build slave

To do this, you need to be able to build OO.o already; if you can't do this start here: Building.

The very basics

As mentioned earlier, the tinderbox works by collecting the buildlogs. So all you need to do is to mail your logs to the tinderbox-server. The scripts presented further down automate this process, but let's have a look at the mails first.

Necessary annotations to the buildlogs

To be able to assign a logfile to a given buildslave, the mail must contain some lines that identify the buildslave and the cws the log belongs to. An example of the fields looks like this:

tinderbox: administrator: John Doe <john@doe.com>
tinderbox: buildname:     LinuxPPC (gcc 4.0.2)
tinderbox: tree:          SRC680_m198
tinderbox: errorparser:   unix
tinderbox: starttime:     1168270122
tinderbox: timenow:       1168286928
tinderbox: status:        success
tinderbox: END

<buildlog goes here>

The fields should be almost self-explanatory, but still:

Admin is the person to contact when there are problems with the buildslave/questions about it
buildname is the identifier of the buildslave as it will appear in the overview pages
tree identifies the Milestone/CWS that the buildslaves reports
errorparser identifies the parser the tinderbox uses to detect build errors within the log - OOo's tinderbox currenlty uses "unix" errorparser for all platfomrs
starttime is the timestamp when the build started (human-readable times possible as well)
timenow is the timestap when the mail is sent
status is the current state of the build (valid values are "building", "success" "failed", "test_failed", "not_running")

The buildlog follows the annotations.

Sending the buildlog gzipped compressed

To save both bandwidth and diskscpace (and to be in the max-message-size limit of most mail-servers), the tinderbox accepts buildlogs in gzipped format. So send gzipped mails, prepare the log as you would do with a plaintext-only message (i.e.)

<tinderbox annotations>

<buildlog>

And run gzip over the message. Then simply add it as attachment to the mail (the mail can then be empty, the body text is ignored).

Let tinderbox know whether it is a plaintext log or a gzipped one

In order to let tinderbox know that it is a gzipped compressed logfile, add a custom header to your mail:

if your log is in the message body add

X-Tinder: cookie

if your log is attached as a gzipped attachment add

X-Tinder: gzookie

The address to send the mails to is tinderbox <at> gimli.documentfoundation.org btw :-) The above info should be enough to allow reporting your logs to tinderbox. If you seek more comport, set up a framework that automates building of OOo (see further below)

How many mails should I send?

Well, at the bare minimum you only need to send one single mail, but sending two mails (one when the build starts and one when the build finishes) allows the tinderbox to give estimations on when a build will be finished (and allow other buildslaves of a similar setup to skip the tree and build another one instead. Another good way is to send a third mail in between, after configure/bootstrap is finished. That way one can check out whether patches that are added were applied successfully and whether configure setup is OK.

Framework to automate the process

The framework that is described in the following sections can be used to build "new" and "Ready-for-QA" CWSs and MWSs of the 680er codeline. The source is fetched from cvs.

See this webpage for a list of the currently accepted tags. You will find the build logs (providing there are any) when you click on the corresponding tag.

Requirements

A mininimal framework to build OOo CWSs and MWSs and sent the reports to the tinderbox at go-oo.org is created by the following files.

These three files from this directory are needed to refresh the build tree and send the build log after the build: (Files partially updated: 2006.07.02)

tin-main.pl
tinget.pl
tinsend.pm

In principle any build/preparation script can be used but the following two files (also from here) work together with the main tinderbox slave script mentioned above (tin-main.pl): (Files partially updated: 2006.06.25)

tinprep.sh
tinbuild.sh

If you want to use your own scripts instead make sure to adapt the lines that call tinprep.sh and tinbuild.sh in tin-main.pl.

In addition to these files you need to install the Sender.pm Perl module from CPAN. See the CPAN_install page for details about getting/installing perl modules.

Configuration

A few files have to be adapted to match your local setup. Changes only have to be done in areas marked with:

"# -- End of Things to tweak --"

tin-main.pl
These variables need to be adapted (Follow the example in the source):

$tinsend::FROMADDRESS

For smtpservers that doesn't need authentification just enter the server name:

$tinsend::SMTPAUTH = '';
$tinsend::SMTPSERVER = 'smtpserver.without_pw.org';
$tinsend::SMTPAUTHID = '';
$tinsend::SMTPAUTHPW = '';

If the smtpserver needs authentification set $SMTPAUTH to 'LOGIN' and set your username and password:

$tinsend::SMTPAUTH = 'LOGIN';
$tinsend::SMTPSERVER = 'smtpserver.without_pw.org';
$tinsend::SMTPAUTHID = 'userid';
$tinsend::SMTPAUTHPW = 'password';

tinbuild.sh
Set the options to configure your OOo build.
tinprep.sh
OOo needs some things prepared before it can be build. Things like that go into this file.

Start the tinderbox build

The build is then started with:

./tin-main.pl "OOoW32(opti)" /cygdrive/d/w1/SRC680_m146 SRC680_m146 co send

The first parameter sets the name the build identifies itself, the second gives the target directory the source is build in, the third sets which CWS/MWS is used (see here for allowed values), the fourth how the source is obtained/treated (checked out from cvs in this case) and the last one says that the buildlog is send to the tinderbox. The parameters are discussed in detail later in this document.

Documentation

The following part describes the used scripts and useful parameters. (The markup needs a brush-up.)

tin-main.pl
Syntax (all five parameters are needed):
tin-main.pl buildstring src_path ws {co|up|cont|clean} {send|nosend} [buildshell]
  buildstring - Name that will appear in the tinderbox
  src_path    - Pointing to source to be used
  ws          - Which workspace shall be build. It accepts CWSs names (from the
                list in <http://go-oo.org/tinderbox/tags/tag-list>) or all MWSs
                starting with ???680_m*.
  co|up|cont|clean - Tells the script what to do with src_path. Fresh checkout,
                update a current repo (this also deletes modified/extra files),
                do nothing, just start/continue with current repo, and clean
                removes all wntmsci10.pro before rebuilding.
  send|nosend - send the logfile to the tinderbox (or not)
  buildshell  - Choose from tcsh, bash or 4nt which shell to use for the build.
                This parameter is optional, the default is tcsh.

The main program that starts the build, captures the logfile and sends it to
the tinderbox.

Example: ./tin-main.pl "OOoW32(opti)" /cygdrive/d/w1/SRC680_m146 SRC680_m146 co send


tinsend.pl
This module handles sending of mails with attachments. This was necessary
because the windows build logs are easily 30MB or more and in our early
setups this was just to much to be handled by some SMTP servers and also
for go-oo.org. See some documentation inline in that file.


tinget.pl
Syntax (all four parameters are needed):
tinget.pl ws buildlog src_path {co|up|cont|clean}
  ws          - See tinder-main.pl.
  buildlog    - logfile name (this is send to the tinderbox)
  src_path    - See tinder-main.pl.
  {co|up|cont|clean} - See tinder-main.pl.

This script does the workspace (src_path) handling.


tinbuild.sh
Syntax:
tinbuild.sh ws buildlog src_path [buildshell]
  Parameter see tinder-main.pl, buildshell is optional.

The actual build script that starts the build and captures the logfile.


tinprep.sh
Syntax:
tinprep.sh src_path [ws] [buildshell]
  Parameter see tinder-main.pl, ws and buildshell are optional.

Prepare the workspace for the build

Alternative tinderbox script

Please note that this script is independent of the framework mentioned above. Don't mix the instructions!

If you don't want to use the modular framework you can still use the former, not mail-compressing version. Get the tinder-build script and edit it to suit your needs:

The script will get http://go-oo.org/tinderbox/tags/tag-list and build all of the included CWSs. You will want to change that.

Choose a buildname

$BUILDNAME = 'My BuildName';

This script already includes a build script. You have to work through this to adapt it to your needs.

Mailer - you need a mailer to send mail with tinder-build, check that you have sendmail configured right, or hack the script to use your mailer.

$MTA = '/usr/bin/mail';

Problem - It sends fine but nothing shows up

There are two issues that may cause this. First, the tinderbox web-pages are re-built every 10 minutes using a cron job; so wait for 11 before getting to concerned.

The second thing is more crucial, since the tinderbox organises the logs chronologically, it is vital to ensure that your system time is not ahead of the tinderbox's, and that it is in the same decade, week, hour, minute etc.

Finally, it's possible that someone else has sent in corrupt logs that are stopping the script completing. See here if the mail arrived, here if there were errors processing it and here for any potential error messages from the demon.

Difference between revisions of "Tinderbox Setup"