osimons@599: .. -*- mode: rst; encoding: utf-8 -*- osimons@599: osimons@599: ============= osimons@599: Configuration osimons@599: ============= osimons@599: osimons@599: While the `Recipe`_ contains the instructions for how to build, osimons@599: configurations are used to determine what gets built and any runtime osimons@599: parameters used when building. osimons@599: osimons@599: .. _recipe: recipe.html osimons@599: osimons@599: .. contents:: Contents osimons@599: :depth: 2 osimons@599: .. sectnum:: osimons@599: osimons@599: Target platforms osimons@599: ================ osimons@599: osimons@599: A target platform is something like 'NetBSD x86' or 'Win32 Java 1.4'. osimons@599: osimons@599: Technically, a target platform is a named set of rules against which the osimons@599: properties of build slaves are matched. Each rule is a regular expression osimons@599: matching a particular slave property, such as the operating system osimons@599: or the processor. When a slave connects to the build master, it sends a osimons@599: registration message that includes information about the slave. osimons@599: osimons@599: A build configuration must have at least one target platform assigned to osimons@599: it before it becomes fully active. osimons@599: osimons@599: Slave Properties osimons@599: ================ osimons@599: osimons@599: By default, the following properties are included: osimons@599: osimons@599: :`family`: The basic type of operating system, typically “posix” for osimons@599: Unix-like systems and “nt” for Win32 systems. osimons@599: :`os`: The name of the operating system (for example “Darwin”, osimons@599: “Linux” or “Windows”). osimons@599: :`version`: The operating system version. osimons@599: :`machine`: The hardware platform (for example “i686” or “Power Macintosh”). osimons@599: :`processor`: The processor architecture (for example “athlon” or “powerpc”). osimons@599: osimons@599: Note that not all of these properties may be available for all platforms, osimons@599: depending on OS and Python version. osimons@599: osimons@599: Examples osimons@599: -------- osimons@599: osimons@599: To set up a target platform, create rules that are checked against the osimons@599: properties of the slave. For example, a target platform that matches slave osimons@599: running Linux on x86 would look like this: osimons@599: osimons@599: +------------+------------------------------------+ osimons@599: + Property | Expression | osimons@599: +============+====================================+ osimons@599: | `os` | `^Linux` | osimons@599: +------------+------------------------------------+ osimons@599: | `machine` | `^[xi]\d?86$` | osimons@599: +------------+------------------------------------+ osimons@599: osimons@599: A target platform that matches any slaves running on Windows might look osimons@599: like this: osimons@599: osimons@599: +------------+------------------------------------+ osimons@599: + Property | Expression | osimons@599: +============+====================================+ osimons@599: | `family` | `^nt$` | osimons@599: +------------+------------------------------------+ osimons@599: osimons@599: The build master will request a build from at most one slave for every osimons@599: target platform. So, for example, if there are three slaves connected that osimons@599: are matching 'NetBSD x86', only one of them will perform the build of a osimons@599: specific revision. Slaves that match a particular target platform are osimons@599: treated as if they were completely interchangable. osimons@599: osimons@599: If a slave connects that doesn't match any of the configured target platforms, osimons@599: the build master will reject its registration. osimons@599: osimons@599: Slave Configuration osimons@599: =================== osimons@599: osimons@599: When a build slave registers with a build master, it sends information about osimons@599: the machine the slave is running on, and what software it has available. osimons@599: While some of this information can be automatically discovered by the slave, osimons@599: other information may need to be configured explicitly. Also, a slave instance osimons@599: may want to override some of the automatically computed attributes, osimons@599: for example to enable cross-compilation. osimons@599: osimons@599: There are three categories of information that can be configured for a slave: osimons@599: osimons@599: :`os`: Properties of the operating system osimons@599: :`machine`: Properties of the underlying hardware osimons@599: :`packages`: Various pieces of software, like a language runtime or a library osimons@599: osimons@599: Configuration File Format osimons@599: ------------------------- osimons@599: osimons@599: For simple manual editing, the slave configuration file will be based on osimons@599: the ``'INI'`` file format known from Windows, which is also frequently used by osimons@599: Python applications. osimons@599: osimons@599: The file is included at runtime using a slave command-line option:: osimons@599: osimons@599: bitten-slave -f config.ini osimons@599: osimons@599: A configuration file is partitioned into named sections. There are two osimons@599: predefined sections named ``[machine]`` and ``[os]``. If you supply them in osimons@599: your configuration file they should include the following sections. osimons@599: osimons@599: .. code-block:: ini osimons@599: osimons@599: [os] osimons@599: name = Darwin osimons@599: version = 8.1.0 osimons@599: family = posix osimons@599: osimons@599: [machine] osimons@599: name = levi osimons@599: processor = Power Macintosh osimons@599: osimons@599: There may be any number of additional sections, where each section corresponds osimons@599: to a software package. For example: osimons@599: osimons@599: .. code-block:: ini osimons@599: osimons@599: [dbxml] osimons@599: version = 2.1.8 osimons@599: osimons@599: [python] osimons@599: version = 2.3.5 osimons@599: path = /usr/bin/python2.3 osimons@599: osimons@599: The build slave sends this package information as part of the build initiation, osimons@599: which when using verbose logging (``bitten-slave -v``) will display a debug osimons@599: message 'Sending slave configuration:' followed by: osimons@599: osimons@599: .. code-block:: xml osimons@599: osimons@599: osimons@599: levi osimons@599: Darwin osimons@599: osimons@599: osimons@599: osimons@599: osimons@599: The name of the slave can only be set as command-line option:: osimons@599: osimons@599: bitten-slave --name=myhost osimons@599: osimons@599: Commands using Properties osimons@599: ------------------------- osimons@599: osimons@599: A number of commands_ support runtime settings using a slave configuration osimons@599: file. The example of ``python.path`` above is one such example, where all osimons@599: Python commands will use the specified executable for running commands. osimons@599: osimons@599: The documentation for commands_ should include information about all osimons@599: runtime settings. osimons@599: osimons@599: .. _commands: commands.html osimons@599: osimons@599: Properties in Build Configurations osimons@599: ---------------------------------- osimons@599: osimons@599: Defined properties can be used in a build configuration to match slaves osimons@599: against target platforms. For example, the following rule would match any slave osimons@599: providing 'Berkeley DB XML' version 2.x:: osimons@599: osimons@599: dbxml.version ~= /^2\.\d\.\d.*/ osimons@599: osimons@599: The properties are accessible in dotted notation, where the part before the dot osimons@599: is the package name, and the part after the dot is the name of the property. osimons@599: osimons@599: Property Interpolation in Build Recipes osimons@599: --------------------------------------- osimons@599: osimons@599: Property values can be interpolated into build recipes_ as well, so individual osimons@599: slaves can parameterize how their build is perfomed. For example, given the osimons@599: following build recipe excerpt: osimons@599: osimons@599: .. code-block:: xml osimons@599: osimons@599: osimons@599: osimons@599: .. _recipes: recipes.html osimons@599: osimons@599: Slaves may control which part of the repository is checked out and tested osimons@599: with a configuration file excerpt like this one: osimons@599: osimons@599: .. code-block:: ini osimons@599: osimons@599: [repository] osimons@599: branch = /branches/0.3-testing osimons@599: osimons@599: Authentication osimons@599: ============== osimons@599: osimons@599: Authentication information can also be included in slave configuration file: osimons@599: osimons@599: .. code-block:: ini osimons@599: osimons@599: [authentication] osimons@599: username = myusername osimons@599: password = mypassword osimons@599: osimons@599: The authentication information will be removed as soon as it is read osimons@599: by the slave, and will not be passed to the master as active configuration.