= Bitten Build Slave Configuration =

{{{
#!div class=important
The content on this page is maintained as part of default documentation - see [wiki:Documentation/configure.html]
}}}

When a build slave [wiki:MasterSlaveProtocol#SlaveRegistration registers] with a build master, it sends information about the machine the slave is running on, and what software it has available. The build master uses this information for matching the slave against [wiki:BuildConfigurations#Targetplatforms target platform rules]. While some of this information can be automatically discovered by the slave, other information may need to be configured explicitly. Also, a slave instance may want to override some of the automatically computed attributes, for example to enable cross-compilation.

There are three categories of information that can be configured for a slave:

 os:: Properties of the operating system
 machine:: Properties of the underlying hardware
 packages:: Various pieces of software, such as a language runtime, a library, etc.

== Configuration File Format ==

For simple manual editing, the slave configuration file will be based on the “INI” file format known from Windows, which is also frequently used by Python applications and supported by Pythons´ [http://docs.python.org/lib/module-ConfigParser.html ConfigParser] module.

A configuration file is partitioned into named sections. There are two predefined sections named {{{[machine]}}} and {{{[os]}}}. If you supply them in your configuration file they should include the following sections.

{{{
#!ini
[os]
name = Darwin
version = 8.1.0
family = posix

[machine]
name = levi
processor = Power Macintosh
}}}

There may be any number of additional sections, where each section corresponds to a software package. For example:

{{{
#!ini
[dbxml]
version = 2.1.8

[python]
version = 2.3.5
path = /usr/bin/python2.3
}}}

The build slave sends this package information as part of the build initiation, which then might look like this:

{{{
#!xml
POST http://example.com/builds HTTP/1.1
Host: example.com
Content-Type: application/x-bitten+xml
Content-Length: 123

<register name="levi" maintainer="Christopher Lenz &lt;cmlenz@gmx.de&gt;">
  <platform>Power Macintosh</platform>
  <os family="posix" version="8.1.0">Darwin</os>
  <package name="dbxml" version="2.1.8" />
  <package name="python" version="2.3.5" path="/usr/bin/python23" />
</register>
}}}

== Authentication ==

Since 0.6dev r619, authentication information can also be included in configuration file:
{{{
#!ini
[authentication]
username = myusername
password = mypassword
}}}

The authentication information will be removed as soon as it is read.

== Using Properties in BuildConfigurations ==

These properties can then be used in a [wiki:BuildConfigurations build configuration] to match slaves against target platforms. For example, the following rule would match any slave providing [http://www.sleepycat.com/products/xml.shtml Berkeley DB XML] version 2.x:

{{{
  dbxml.version ~= /^2\.\d\.\d.*/
}}}

The properties are accessible in dotted notation, where the part before the dot is the package name, and the part after the dot is the name of the property.  

== Property Interpolation in BuildRecipes ==

Property values can be interpolated into [BuildRecipes build recipes] as well, so individual slaves can parameterize how their build is perfomed.  For example, given the following [BuildRecipe build recipe] excerpt:
{{{
<svn:checkout url="http://svn.example.org/repos/myproject/"
    path="${repository.branch}" revision="${revision}"/>
}}}
Slaves may control which part of the repository is checked out and tested with a configuration file excerpt like this one:
{{{
[repository]
branch=/branches/0.3-testing
}}}

See BuildRecipes for more information.