
Contents
 
 1. This is the Xenofarm client
 2. Compiling "put"
 3. Other requirements
 4. Configuring the client
 5. Setting up the client

1. This is the Xenofarm client.

You need to install this software on each machine you intend to attach
to the Xenofarm as a compile and test client. To ensure that it is as
easy as possible to set up on new and strange OSes the main part if
the client in written in pure Posix sh, calling a few external
binaries to handle the network communication with the Xenofarm server.


2. Compiling "put".

The binary program put will be built automatically when you start the
Xenofarm client, so you can skip this section if you don't want to
compile it manually for usage outside Xenofarm.

The Xenofarm client needs a program called put that does the job of
returning the result from the compiled and tested project to the
project result collector by way of HTTP PUT. The put program is a
small program written specifically for the Xenofarm client in highly
portable C.

To compile it manually, run the normal ./configure && make.


3. Other requirements.

wget	GNU wget, must accept and handle the -N and --referer parameters.
gzip	GNU gzip.

Both can be downloaded from your nearest GNU mirror. See
http://www.gnu.org/prep/ftp.html for a list of mirrors.

NOTE: There is a known bug in wget 1.6 and prior versions that will
      cause occasional missed builds. Versions 1.8.2 and newer are
      known to work. Versions between 1.6 and 1.8.2 are untested.

If your system is strange (ie not Posix compliant) the commands the
system must supply are listed in the topmost comment in client.sh.
Check that they are available in your client's PATH.


4. Configuring the client.

client.sh builds and tests projects based on configuration files
stored in the "config" directory. Each project has its own configuration
file, but each configuration may contain several tests to be done on the
same project.

Configuration file names must have the extension ".cfg" or they will
not be considered by the client. The file itself consists of a list of
configuration name/value bindings separated by a colon. A
configuration file must have these configurations:

configformat:     3
project:          <Project name>
projectdir:       <Project test directory relative to cwd. Avoid spaces>
snapshoturl:      <URL to GET the snapshot from>
resulturl:        <URL to PUT the result too>
test: <testname>  <test commands that will be executed inside the 
                   unarchived snapshot. One line. Newlines cannot be quoted>

If the client detects a line it doesn't know how to handle it will
fail and skip the associated project.

An arbitrary number of "test:" lines can be added to the
configuration. Note that the "test:" lines must come last in the
configuration file. <testname> should be low on funny characters as it
will be used in file and directory names.

If several build nodes share the same configuration file node specific
tests can be specified by inserting lines _before_ the regular test
directives, but after all other directives, on the format: 
test-<nodename>: <testname> <test commands>

<nodename> is the result of `uname -n`. The regular test: directives
will be ignored on nodes that have one or more corresponding
test-<nodename> directives.

An alternative way of specifying node specific tests is by creating a
separate configuration file with the filename <original.cfg>.<nodename>.
This configuration file has precedence over <original.cfg> and will not
inherit any setting from that file.

BUGS: Multiple adjacent spaces in a <test commands> will be merged into
      one space. Commands like `make CC="/odd/p    ath/cc" will therefor
      fail.

Since version 3 of the config format one can optionally add one or
more "enviroment:" lines before the "test:" statements. The lines
should contain one or more varable assignments on standard sh format.
These variables will be exported to all test enviroments. Example:

enviroment:       CC=gcc MAKE=gmake

Each client installation also has a config/contact.txt that should
list a contact address for the person responsible for that particular
client installation. The client will automatically ask for an email
address the first time it starts up.


5.  Setting up the client.

To check that your client setup is working and to configure the
contact email address run `./client.sh` once manually and make sure it
completes properly and sends the result to the result collector.

The normal way of running the Xenofarm client is to make an entry in
the crontab. Do not write the crontab entry until after you have run
the client successfully manually, though.

Examples:

 # This entry will check for new snapshots to test once per hour, 24
 # minutes past full hour. The path to where you have your client must
 # be changed to where you have your client of course.
 24 * * * * cd $HOME/xenofarm/client/ && ./client.sh 1>/dev/null
 
 # This entry will check for new snapshots to test once per day, 24
 # minutes past 2 o'clock in the morning. The path to where you have
 # your client must be changed to where you have your client.
 24 2 * * * cd $HOME/xenofarm/client/ && ./client.sh 1>/dev/null

The "1>/dev/null" will make sure that you only get emails from the
cron daemon when something goes seriously wrong. You can leave it out
if you wish to get a complete log mailed to you every time the client
is started.

NOTE: There is no problem with letting it run often, since it will
      make sure there isn't another client already running and check
      if there is a new snapshot available before downloading anything.
