# HG changeset patch # User osimons # Date 1248947268 0 # Node ID b76e6accad72d4c6f560cc50db66c80d46a6cf62 # Parent 5f3e66e5b451ae9f51a582941fc121a6700075f3 0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code. diff --git a/bitten/build/config.py b/bitten/build/config.py --- a/bitten/build/config.py +++ b/bitten/build/config.py @@ -30,7 +30,6 @@ information and stores them as properties. These defaults can be overridden (useful for cross-compilation). """ - # TODO: document mapping from config file to property names def __init__(self, filename=None, properties=None): """Create the configuration object. diff --git a/doc/commands.txt b/doc/commands.txt --- a/doc/commands.txt +++ b/doc/commands.txt @@ -5,11 +5,13 @@ ===================== `Build recipes`_ are represented by XML documents. This page describes what -commands are generally available in recipes. Please note, though, that +commands are generally available in recipes, and any `runtime configuration`_ +supported by these commands. Please note, though, that third-party packages can add additional commands, which would then be documented by that third party. .. _`build recipes`: recipes.html +.. _`runtime configuration`: configure.html .. contents:: Contents :depth: 2 @@ -213,6 +215,15 @@ ./configure --enable-threadsafe CFLAGS="-O" +Configuration +------------- + +Parameter ``with`` will expand any package found in slave configuration: + +.. code-block:: ini + + [mylib] + path = /path/to/mylib ------------ ```` @@ -269,7 +280,6 @@ | | ``"parameter1=value1 parameter2=value2"``. | +----------------+-----------------------------------------------------------+ - Examples -------- @@ -287,6 +297,14 @@ Same as previous but execute the command in the ``work`` directory and call the makefile with the command line argument ``coverage=1``. +Configuration +------------- + +.. code-block:: ini + + [make] + path = /path/to/(c|n)make + --------------- ```` --------------- @@ -363,6 +381,17 @@ Executes the target ``compile`` of the ``build.xml`` buildfile at the top of the project source directory. +Configuration +------------- + +.. code-block:: ini + + [ant] + home = /path/to/ant/dir + + [java] + home = /path/to/java/dir + -------------------- ```` @@ -616,6 +645,14 @@ Executes Pylint_ on the module/package ``myproj`` and stores the output into a file named ``pylint-report.txt``. +Configuration +------------- + +.. code-block:: ini + + [python] + path = /path/to/python + ---------------------- ```` @@ -657,6 +694,14 @@ Bitten), and passes the options needed to determine the output paths for test results and code coverage reports. +Configuration +------------- + +.. code-block:: ini + + [python] + path = /path/to/python + --------------------- ```` diff --git a/doc/configure.txt b/doc/configure.txt new file mode 100644 --- /dev/null +++ b/doc/configure.txt @@ -0,0 +1,209 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +============= +Configuration +============= + +While the `Recipe`_ contains the instructions for how to build, +configurations are used to determine what gets built and any runtime +parameters used when building. + +.. _recipe: recipe.html + +.. contents:: Contents + :depth: 2 +.. sectnum:: + +Target platforms +================ + +A target platform is something like 'NetBSD x86' or 'Win32 Java 1.4'. + +Technically, a target platform is a named set of rules against which the +properties of build slaves are matched. Each rule is a regular expression +matching a particular slave property, such as the operating system +or the processor. When a slave connects to the build master, it sends a +registration message that includes information about the slave. + +A build configuration must have at least one target platform assigned to +it before it becomes fully active. + +Slave Properties +================ + +By default, the following properties are included: + +:`family`: The basic type of operating system, typically “posix” for + Unix-like systems and “nt” for Win32 systems. +:`os`: The name of the operating system (for example “Darwin”, + “Linux” or “Windows”). +:`version`: The operating system version. +:`machine`: The hardware platform (for example “i686” or “Power Macintosh”). +:`processor`: The processor architecture (for example “athlon” or “powerpc”). + +Note that not all of these properties may be available for all platforms, +depending on OS and Python version. + +Examples +-------- + +To set up a target platform, create rules that are checked against the +properties of the slave. For example, a target platform that matches slave +running Linux on x86 would look like this: + ++------------+------------------------------------+ ++ Property | Expression | ++============+====================================+ +| `os` | `^Linux` | ++------------+------------------------------------+ +| `machine` | `^[xi]\d?86$` | ++------------+------------------------------------+ + +A target platform that matches any slaves running on Windows might look +like this: + ++------------+------------------------------------+ ++ Property | Expression | ++============+====================================+ +| `family` | `^nt$` | ++------------+------------------------------------+ + +The build master will request a build from at most one slave for every +target platform. So, for example, if there are three slaves connected that +are matching 'NetBSD x86', only one of them will perform the build of a +specific revision. Slaves that match a particular target platform are +treated as if they were completely interchangable. + +If a slave connects that doesn't match any of the configured target platforms, +the build master will reject its registration. + +Slave Configuration +=================== + +When a build slave registers with a build master, it sends information about +the machine the slave is running on, and what software it has available. +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, like a language runtime or a library + +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. + +The file is included at runtime using a slave command-line option:: + + bitten-slave -f config.ini + +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. + +.. code-block:: 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: + +.. code-block:: 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 when using verbose logging (``bitten-slave -v``) will display a debug +message 'Sending slave configuration:' followed by: + +.. code-block:: xml + + + levi + Darwin + + + + +The name of the slave can only be set as command-line option:: + + bitten-slave --name=myhost + +Commands using Properties +------------------------- + +A number of commands_ support runtime settings using a slave configuration +file. The example of ``python.path`` above is one such example, where all +Python commands will use the specified executable for running commands. + +The documentation for commands_ should include information about all +runtime settings. + +.. _commands: commands.html + +Properties in Build Configurations +---------------------------------- + +Defined properties can be used in a build configuration to match slaves +against target platforms. For example, the following rule would match any slave +providing '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 Build Recipes +--------------------------------------- + +Property values can be interpolated into build recipes_ as well, so individual +slaves can parameterize how their build is perfomed. For example, given the +following build recipe excerpt: + +.. code-block:: xml + + + +.. _recipes: recipes.html + +Slaves may control which part of the repository is checked out and tested +with a configuration file excerpt like this one: + +.. code-block:: ini + + [repository] + branch = /branches/0.3-testing + +Authentication +============== + +Authentication information can also be included in slave configuration file: + +.. code-block:: ini + + [authentication] + username = myusername + password = mypassword + +The authentication information will be removed as soon as it is read +by the slave, and will not be passed to the master as active configuration. diff --git a/doc/index.txt b/doc/index.txt --- a/doc/index.txt +++ b/doc/index.txt @@ -22,5 +22,5 @@ * `Installation `_ * `Build Recipes `_ * `Build Recipe Commands `_ + * `Configuration `_ * `Build Links `_ - * `Generated API Documentation `_ diff --git a/doc/recipes.txt b/doc/recipes.txt --- a/doc/recipes.txt +++ b/doc/recipes.txt @@ -36,6 +36,10 @@ these elements are declared in XML namespaces, where the namespace URI defines a collection of related commands. +A `````element can additionally have a ``onerror`` attribute with possible +values of ``fail`` (terminate after step, default behaviour), or ``continue`` +(fail, but run next step), or ``ignore`` (errors are unimportant, continue). + Commonly, the first step of any build recipe will perform the checkout from the repository. @@ -67,6 +71,24 @@ .. _`build recipe commands`: commands.html +Recipes supports variables that can be interpolated into recipes, and using +`Slave Configuration`_ further custom properties can be used. Bitten supports +these pre-defined properties: + +.. _`slave configuration`: slaveconfig.html + ++-----------------+----------------------------------------------------------+ +| Constant | Value | ++=================+==========================================================+ +| ``${path}`` | Repository path from the build configuration | ++-----------------+----------------------------------------------------------+ +| ``${config}`` | The build configuration name | ++-----------------+----------------------------------------------------------+ +| ``${build}`` | The index of this build request | ++-----------------+----------------------------------------------------------+ +| ``${revision}`` | The repository revision being tested | ++-----------------+----------------------------------------------------------+ + As the recipe needs to be valid XML, any reserved characters in attributes must be quoted using regular XML entities: