Revision as of 03:16, 29 March 2006

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 is a perl script that processes mail, and turns it into HTML. It expects to be mailed build 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 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.02.25)

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.02.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 link <http://go-ooo.org/cpan.html> for details about getting this module.

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}
  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)

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 buildsys buildlog src_path
  Parameter see tinder-main.pl, buildsys includes {cyg|4nt} but can also
  handle several special cases.

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


tinprep.sh
Syntax:
tinprep.sh src_path

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.