<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Configuration — Buildbot 0.8.12 documentation</title>
<link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.12',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/buildbot.ico"/>
<link rel="top" title="Buildbot 0.8.12 documentation" href="../index.html" />
<link rel="up" title="Buildbot Development" href="index.html" />
<link rel="next" title="Utilities" href="utils.html" />
<link rel="prev" title="Buildbot's Test Suite" href="tests.html" />
</head>
<body role="document">
<div class="header-wrapper" role="banner">
<div class="header">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/header-text-transparent.png" alt="Logo"/>
</a></p>
<div class="headertitle"><a
href="../index.html">Buildbot 0.8.12 documentation</a></div>
<div class="rel" role="navigation" aria-label="related navigation">
<a href="tests.html" title="Buildbot's Test Suite"
accesskey="P">previous</a> |
<a href="utils.html" title="Utilities"
accesskey="N">next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
accesskey="I">index</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="module-buildbot.config">
<span id="configuration"></span><h1>Configuration<a class="headerlink" href="#module-buildbot.config" title="Permalink to this headline">¶</a></h1>
<p>Wherever possible, Buildbot components should access configuration information
as needed from the canonical source, <code class="docutils literal"><span class="pre">master.config</span></code>, which is an instance of
<a class="reference internal" href="#buildbot.config.MasterConfig" title="buildbot.config.MasterConfig"><code class="xref py py-class docutils literal"><span class="pre">MasterConfig</span></code></a>. For example, components should not keep a copy of
the <code class="docutils literal"><span class="pre">buildbotURL</span></code> locally, as this value may change throughout the lifetime
of the master.</p>
<p>Components which need to be notified of changes in the configuration should be
implemented as services, subclassing <a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin" title="buildbot.config.ReconfigurableServiceMixin"><code class="xref py py-class docutils literal"><span class="pre">ReconfigurableServiceMixin</span></code></a>, as
described in <a class="reference internal" href="#developer-reconfiguration"><span class="std std-ref">Reconfiguration</span></a>.</p>
<dl class="class">
<dt id="buildbot.config.MasterConfig">
<em class="property">class </em><code class="descclassname">buildbot.config.</code><code class="descname">MasterConfig</code><a class="headerlink" href="#buildbot.config.MasterConfig" title="Permalink to this definition">¶</a></dt>
<dd><p>The master object makes much of the configuration available from an object
named <code class="docutils literal"><span class="pre">master.config</span></code>. Configuration is stored as attributes of this
object. Where possible, other Buildbot components should access this
configuration directly and not cache the configuration values anywhere
else. This avoids the need to ensure that update-from-configuration
methods are called on a reconfig.</p>
<p>Aside from validating the configuration, this class handles any
backward-compatibility issues - renamed parameters, type changes, and so on
- removing those concerns from other parts of Buildbot.</p>
<p>This class may be instantiated directly, creating an entirely default
configuration, or via <a class="reference internal" href="#buildbot.config.MasterConfig.loadConfig" title="buildbot.config.MasterConfig.loadConfig"><code class="xref py py-meth docutils literal"><span class="pre">loadConfig</span></code></a>, which will load the
configuration from a config file.</p>
<p>The following attributes are available from this class, representing the
current configuration. This includes a number of global parameters:</p>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.title">
<code class="descname">title</code><a class="headerlink" href="#buildbot.config.MasterConfig.title" title="Permalink to this definition">¶</a></dt>
<dd><p>The title of this buildmaster, from <a class="reference internal" href="../manual/cfg-global.html#cfg-title" title="title"><code class="xref bb bb-cfg docutils literal"><span class="pre">title</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.titleURL">
<code class="descname">titleURL</code><a class="headerlink" href="#buildbot.config.MasterConfig.titleURL" title="Permalink to this definition">¶</a></dt>
<dd><p>The URL corresponding to the title, from <a class="reference internal" href="../manual/cfg-global.html#cfg-titleURL" title="titleURL"><code class="xref bb bb-cfg docutils literal"><span class="pre">titleURL</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.buildbotURL">
<code class="descname">buildbotURL</code><a class="headerlink" href="#buildbot.config.MasterConfig.buildbotURL" title="Permalink to this definition">¶</a></dt>
<dd><p>The URL of this buildmaster, for use in constructing WebStatus URLs;
from <a class="reference internal" href="../manual/cfg-global.html#cfg-buildbotURL" title="buildbotURL"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildbotURL</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.changeHorizon">
<code class="descname">changeHorizon</code><a class="headerlink" href="#buildbot.config.MasterConfig.changeHorizon" title="Permalink to this definition">¶</a></dt>
<dd><p>The current change horizon, from <a class="reference internal" href="../manual/cfg-global.html#cfg-changeHorizon" title="changeHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">changeHorizon</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.eventHorizon">
<code class="descname">eventHorizon</code><a class="headerlink" href="#buildbot.config.MasterConfig.eventHorizon" title="Permalink to this definition">¶</a></dt>
<dd><p>The current event horizon, from <a class="reference internal" href="../manual/cfg-global.html#cfg-eventHorizon" title="eventHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">eventHorizon</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.logHorizon">
<code class="descname">logHorizon</code><a class="headerlink" href="#buildbot.config.MasterConfig.logHorizon" title="Permalink to this definition">¶</a></dt>
<dd><p>The current log horizon, from <a class="reference internal" href="../manual/cfg-global.html#cfg-logHorizon" title="logHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">logHorizon</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.buildHorizon">
<code class="descname">buildHorizon</code><a class="headerlink" href="#buildbot.config.MasterConfig.buildHorizon" title="Permalink to this definition">¶</a></dt>
<dd><p>The current build horizon, from <a class="reference internal" href="../manual/cfg-global.html#cfg-buildHorizon" title="buildHorizon"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildHorizon</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.logCompressionLimit">
<code class="descname">logCompressionLimit</code><a class="headerlink" href="#buildbot.config.MasterConfig.logCompressionLimit" title="Permalink to this definition">¶</a></dt>
<dd><p>The current log compression limit, from <a class="reference internal" href="../manual/cfg-global.html#cfg-logCompressionLimit" title="logCompressionLimit"><code class="xref bb bb-cfg docutils literal"><span class="pre">logCompressionLimit</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.logCompressionMethod">
<code class="descname">logCompressionMethod</code><a class="headerlink" href="#buildbot.config.MasterConfig.logCompressionMethod" title="Permalink to this definition">¶</a></dt>
<dd><p>The current log compression method, from
<a class="reference internal" href="../manual/cfg-global.html#cfg-logCompressionMethod" title="logCompressionMethod"><code class="xref bb bb-cfg docutils literal"><span class="pre">logCompressionMethod</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.logMaxSize">
<code class="descname">logMaxSize</code><a class="headerlink" href="#buildbot.config.MasterConfig.logMaxSize" title="Permalink to this definition">¶</a></dt>
<dd><p>The current log maximum size, from <a class="reference internal" href="../manual/cfg-global.html#cfg-logMaxSize" title="logMaxSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">logMaxSize</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.logMaxTailSize">
<code class="descname">logMaxTailSize</code><a class="headerlink" href="#buildbot.config.MasterConfig.logMaxTailSize" title="Permalink to this definition">¶</a></dt>
<dd><p>The current log maximum size, from <a class="reference internal" href="../manual/cfg-global.html#cfg-logMaxTailSize" title="logMaxTailSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">logMaxTailSize</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.properties">
<code class="descname">properties</code><a class="headerlink" href="#buildbot.config.MasterConfig.properties" title="Permalink to this definition">¶</a></dt>
<dd><p>A <code class="xref py py-class docutils literal"><span class="pre">Properties</span></code> instance
containing global properties, from <a class="reference internal" href="../manual/cfg-global.html#cfg-properties" title="properties"><code class="xref bb bb-cfg docutils literal"><span class="pre">properties</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.mergeRequests">
<code class="descname">mergeRequests</code><a class="headerlink" href="#buildbot.config.MasterConfig.mergeRequests" title="Permalink to this definition">¶</a></dt>
<dd><p>A callable, or True or False, describing how to merge requests; from
<a class="reference internal" href="../manual/cfg-global.html#cfg-mergeRequests" title="mergeRequests"><code class="xref bb bb-cfg docutils literal"><span class="pre">mergeRequests</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.prioritizeBuilders">
<code class="descname">prioritizeBuilders</code><a class="headerlink" href="#buildbot.config.MasterConfig.prioritizeBuilders" title="Permalink to this definition">¶</a></dt>
<dd><p>A callable, or None, used to prioritize builders; from
<a class="reference internal" href="../manual/cfg-global.html#cfg-prioritizeBuilders" title="prioritizeBuilders"><code class="xref bb bb-cfg docutils literal"><span class="pre">prioritizeBuilders</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.codebaseGenerator">
<code class="descname">codebaseGenerator</code><a class="headerlink" href="#buildbot.config.MasterConfig.codebaseGenerator" title="Permalink to this definition">¶</a></dt>
<dd><p>A callable, or None, used to determine the codebase from an incoming
<code class="xref py py-class docutils literal"><span class="pre">Change</span></code>,
from <a class="reference internal" href="../manual/cfg-global.html#cfg-codebaseGenerator" title="codebaseGenerator"><code class="xref bb bb-cfg docutils literal"><span class="pre">codebaseGenerator</span></code></a></p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.protocols">
<code class="descname">protocols</code><a class="headerlink" href="#buildbot.config.MasterConfig.protocols" title="Permalink to this definition">¶</a></dt>
<dd><p>The per-protocol port specification for slave connections.
Based on <a class="reference internal" href="../manual/cfg-global.html#cfg-protocols" title="protocols"><code class="xref bb bb-cfg docutils literal"><span class="pre">protocols</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.multiMaster">
<code class="descname">multiMaster</code><a class="headerlink" href="#buildbot.config.MasterConfig.multiMaster" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, then this master is part of a cluster; based on
<a class="reference internal" href="../manual/cfg-global.html#cfg-multiMaster" title="multiMaster"><code class="xref bb bb-cfg docutils literal"><span class="pre">multiMaster</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.debugPassword">
<code class="descname">debugPassword</code><a class="headerlink" href="#buildbot.config.MasterConfig.debugPassword" title="Permalink to this definition">¶</a></dt>
<dd><p>The password for the debug client, or None; from
<a class="reference internal" href="../manual/cfg-global.html#cfg-debugPassword" title="debugPassword"><code class="xref bb bb-cfg docutils literal"><span class="pre">debugPassword</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.manhole">
<code class="descname">manhole</code><a class="headerlink" href="#buildbot.config.MasterConfig.manhole" title="Permalink to this definition">¶</a></dt>
<dd><p>The manhole instance to use, or None; from <a class="reference internal" href="../manual/cfg-global.html#cfg-manhole" title="manhole"><code class="xref bb bb-cfg docutils literal"><span class="pre">manhole</span></code></a>.</p>
</dd></dl>
<p>The remaining attributes contain compound configuration structures, usually
dictionaries:</p>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.validation">
<code class="descname">validation</code><a class="headerlink" href="#buildbot.config.MasterConfig.validation" title="Permalink to this definition">¶</a></dt>
<dd><p>Validation regular expressions, a dictionary from <a class="reference internal" href="../manual/cfg-global.html#cfg-validation" title="validation"><code class="xref bb bb-cfg docutils literal"><span class="pre">validation</span></code></a>.
It is safe to assume that all expected keys are present.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.db">
<code class="descname">db</code><a class="headerlink" href="#buildbot.config.MasterConfig.db" title="Permalink to this definition">¶</a></dt>
<dd><p>Database specification, a dictionary with keys <a class="reference internal" href="../manual/cfg-global.html#cfg-db_url" title="db_url"><code class="xref bb bb-cfg docutils literal"><span class="pre">db_url</span></code></a> and
<a class="reference internal" href="../manual/cfg-global.html#cfg-db_poll_interval" title="db_poll_interval"><code class="xref bb bb-cfg docutils literal"><span class="pre">db_poll_interval</span></code></a>. It is safe to assume that both keys are
present.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.metrics">
<code class="descname">metrics</code><a class="headerlink" href="#buildbot.config.MasterConfig.metrics" title="Permalink to this definition">¶</a></dt>
<dd><p>The metrics configuration from <a class="reference internal" href="../manual/cfg-global.html#cfg-metrics" title="metrics"><code class="xref bb bb-cfg docutils literal"><span class="pre">metrics</span></code></a>, or an empty
dictionary by default.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.caches">
<code class="descname">caches</code><a class="headerlink" href="#buildbot.config.MasterConfig.caches" title="Permalink to this definition">¶</a></dt>
<dd><p>The cache configuration, from <a class="reference internal" href="../manual/cfg-global.html#cfg-caches" title="caches"><code class="xref bb bb-cfg docutils literal"><span class="pre">caches</span></code></a> as well as the
deprecated <a class="reference internal" href="../manual/cfg-global.html#cfg-buildCacheSize" title="buildCacheSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">buildCacheSize</span></code></a> and <a class="reference internal" href="../manual/cfg-global.html#cfg-changeCacheSize" title="changeCacheSize"><code class="xref bb bb-cfg docutils literal"><span class="pre">changeCacheSize</span></code></a>
parameters.</p>
<p>The keys <code class="docutils literal"><span class="pre">Builds</span></code> and <code class="docutils literal"><span class="pre">Caches</span></code> are always available; other keys
should use <code class="docutils literal"><span class="pre">config.caches.get(cachename,</span> <span class="pre">1)</span></code>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.schedulers">
<code class="descname">schedulers</code><a class="headerlink" href="#buildbot.config.MasterConfig.schedulers" title="Permalink to this definition">¶</a></dt>
<dd><p>The dictionary of scheduler instances, by name, from <a class="reference internal" href="../manual/cfg-schedulers.html#cfg-schedulers" title="schedulers"><code class="xref bb bb-cfg docutils literal"><span class="pre">schedulers</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.builders">
<code class="descname">builders</code><a class="headerlink" href="#buildbot.config.MasterConfig.builders" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of <a class="reference internal" href="#buildbot.config.BuilderConfig" title="buildbot.config.BuilderConfig"><code class="xref py py-class docutils literal"><span class="pre">BuilderConfig</span></code></a> instances from
<a class="reference internal" href="../manual/cfg-builders.html#cfg-builders" title="builders"><code class="xref bb bb-cfg docutils literal"><span class="pre">builders</span></code></a>. Builders specified as dictionaries in the
configuration file are converted to instances.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.slaves">
<code class="descname">slaves</code><a class="headerlink" href="#buildbot.config.MasterConfig.slaves" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of <code class="xref py py-class docutils literal"><span class="pre">BuildSlave</span></code> instances from
<a class="reference internal" href="../manual/cfg-buildslaves.html#cfg-slaves" title="slaves"><code class="xref bb bb-cfg docutils literal"><span class="pre">slaves</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.change_sources">
<code class="descname">change_sources</code><a class="headerlink" href="#buildbot.config.MasterConfig.change_sources" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of <code class="xref py py-class docutils literal"><span class="pre">IChangeSource</span></code> providers from
<a class="reference internal" href="../manual/cfg-changesources.html#cfg-change_source" title="change_source"><code class="xref bb bb-cfg docutils literal"><span class="pre">change_source</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.status">
<code class="descname">status</code><a class="headerlink" href="#buildbot.config.MasterConfig.status" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of <code class="xref py py-class docutils literal"><span class="pre">IStatusReceiver</span></code> providers from
<a class="reference internal" href="../manual/cfg-statustargets.html#cfg-status" title="status"><code class="xref bb bb-cfg docutils literal"><span class="pre">status</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.MasterConfig.user_managers">
<code class="descname">user_managers</code><a class="headerlink" href="#buildbot.config.MasterConfig.user_managers" title="Permalink to this definition">¶</a></dt>
<dd><p>The list of user managers providers from <a class="reference internal" href="../manual/cfg-global.html#cfg-user_managers" title="user_managers"><code class="xref bb bb-cfg docutils literal"><span class="pre">user_managers</span></code></a>.</p>
</dd></dl>
<p>Loading of the configuration file is generally triggered by the master,
using the following methods:</p>
<dl class="classmethod">
<dt id="buildbot.config.MasterConfig.loadConfig">
<em class="property">classmethod </em><code class="descname">loadConfig</code><span class="sig-paren">(</span><em>basedir</em>, <em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.config.MasterConfig.loadConfig" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>basedir</strong> (<em>string</em>) -- directory to which config is relative</li>
<li><strong>filename</strong> (<em>string</em>) -- the configuration file to load</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><p class="first"><a class="reference internal" href="#buildbot.config.ConfigErrors" title="buildbot.config.ConfigErrors"><code class="xref py py-exc docutils literal"><span class="pre">ConfigErrors</span></code></a> if any errors occur</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">new <a class="reference internal" href="#buildbot.config.MasterConfig" title="buildbot.config.MasterConfig"><code class="xref py py-class docutils literal"><span class="pre">MasterConfig</span></code></a> instance</p>
</td>
</tr>
</tbody>
</table>
<p>Load the configuration in the given file. Aside from syntax errors,
this will also detect a number of semantic errors such as multiple
schedulers with the same name.</p>
<p>The filename is treated as relative to the basedir, if it is not
absolute.</p>
</dd></dl>
</dd></dl>
<div class="section" id="builder-configuration">
<h2>Builder Configuration<a class="headerlink" href="#builder-configuration" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="buildbot.config.BuilderConfig">
<em class="property">class </em><code class="descclassname">buildbot.config.</code><code class="descname">BuilderConfig</code><span class="sig-paren">(</span><span class="optional">[</span><em>keyword args</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.config.BuilderConfig" title="Permalink to this definition">¶</a></dt>
<dd><p>This class parameterizes configuration of builders; see
<a class="reference internal" href="../manual/cfg-builders.html#builder-configuration"><span class="std std-ref">Builder Configuration</span></a> for its arguments. The constructor checks for
errors and applies defaults, and sets the properties described here. Most
are simply copied from the constructor argument of the same name.</p>
<p>Users may subclass this class to add defaults, for example.</p>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.name">
<code class="descname">name</code><a class="headerlink" href="#buildbot.config.BuilderConfig.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's name.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.factory">
<code class="descname">factory</code><a class="headerlink" href="#buildbot.config.BuilderConfig.factory" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's factory.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.slavenames">
<code class="descname">slavenames</code><a class="headerlink" href="#buildbot.config.BuilderConfig.slavenames" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's slave names (a list, regardless of whether the names were
specified with <code class="docutils literal"><span class="pre">slavename</span></code> or <code class="docutils literal"><span class="pre">slavenames</span></code>).</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.builddir">
<code class="descname">builddir</code><a class="headerlink" href="#buildbot.config.BuilderConfig.builddir" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's builddir.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.slavebuilddir">
<code class="descname">slavebuilddir</code><a class="headerlink" href="#buildbot.config.BuilderConfig.slavebuilddir" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's slave-side builddir.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.category">
<code class="descname">category</code><a class="headerlink" href="#buildbot.config.BuilderConfig.category" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's category.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.nextSlave">
<code class="descname">nextSlave</code><a class="headerlink" href="#buildbot.config.BuilderConfig.nextSlave" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's nextSlave callable.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.nextBuild">
<code class="descname">nextBuild</code><a class="headerlink" href="#buildbot.config.BuilderConfig.nextBuild" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's nextBuild callable.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.canStartBuild">
<code class="descname">canStartBuild</code><a class="headerlink" href="#buildbot.config.BuilderConfig.canStartBuild" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's canStartBuild callable.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.locks">
<code class="descname">locks</code><a class="headerlink" href="#buildbot.config.BuilderConfig.locks" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's locks.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.env">
<code class="descname">env</code><a class="headerlink" href="#buildbot.config.BuilderConfig.env" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's environmnet variables.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.properties">
<code class="descname">properties</code><a class="headerlink" href="#buildbot.config.BuilderConfig.properties" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's properties, as a dictionary.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.mergeRequests">
<code class="descname">mergeRequests</code><a class="headerlink" href="#buildbot.config.BuilderConfig.mergeRequests" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's mergeRequests callable.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.BuilderConfig.description">
<code class="descname">description</code><a class="headerlink" href="#buildbot.config.BuilderConfig.description" title="Permalink to this definition">¶</a></dt>
<dd><p>The builder's description, displayed in the web status.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="error-handling">
<h2>Error Handling<a class="headerlink" href="#error-handling" title="Permalink to this headline">¶</a></h2>
<p>If any errors are encountered while loading the configuration <a class="reference internal" href="#buildbot.config.error" title="buildbot.config.error"><code class="xref py py-func docutils literal"><span class="pre">buildbot.config.error</span></code></a>
should be called. This can occur both in the configuration-loading code,
and in the constructors of any objects that are instantiated in the
configuration - change sources, slaves, schedulers, build steps, and so on.</p>
<dl class="function">
<dt id="buildbot.config.error">
<code class="descclassname">buildbot.config.</code><code class="descname">error</code><span class="sig-paren">(</span><em>error</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.config.error" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>error</strong> -- error to report</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><a class="reference internal" href="#buildbot.config.ConfigErrors" title="buildbot.config.ConfigErrors"><code class="xref py py-exc docutils literal"><span class="pre">ConfigErrors</span></code></a> if called at build-time</td>
</tr>
</tbody>
</table>
<p>This function reports a configuration error. If a config file is being loaded,
then the function merely records the error, and allows the rest of the configuration
to be loaded. At any other time, it raises <a class="reference internal" href="#buildbot.config.ConfigErrors" title="buildbot.config.ConfigErrors"><code class="xref py py-exc docutils literal"><span class="pre">ConfigErrors</span></code></a>. This is done
so all config errors can be reported, rather than just the first.</p>
</dd></dl>
<dl class="exception">
<dt id="buildbot.config.ConfigErrors">
<em class="property">exception </em><code class="descclassname">buildbot.config.</code><code class="descname">ConfigErrors</code><span class="sig-paren">(</span><span class="optional">[</span><em>errors</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.config.ConfigErrors" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>errors</strong> (<em>list</em>) -- errors to report</td>
</tr>
</tbody>
</table>
<p>This exception represents errors in the configuration. It supports
reporting multiple errors to the user simultaneously, e.g., when several
consistency checks fail.</p>
<dl class="attribute">
<dt id="buildbot.config.ConfigErrors.errors">
<code class="descname">errors</code><a class="headerlink" href="#buildbot.config.ConfigErrors.errors" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of detected errors, each given as a string.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.config.ConfigErrors.addError">
<code class="descname">addError</code><span class="sig-paren">(</span><em>msg</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.config.ConfigErrors.addError" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>msg</strong> (<em>string</em>) -- the message to add</td>
</tr>
</tbody>
</table>
<p>Add another error message to the (presumably not-yet-raised) exception.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="reconfiguration">
<span id="developer-reconfiguration"></span><h2>Reconfiguration<a class="headerlink" href="#reconfiguration" title="Permalink to this headline">¶</a></h2>
<p>When the buildmaster receives a signal to begin a reconfig, it re-reads the
configuration file, generating a new <a class="reference internal" href="#buildbot.config.MasterConfig" title="buildbot.config.MasterConfig"><code class="xref py py-class docutils literal"><span class="pre">MasterConfig</span></code></a> instance, and
then notifies all of its child services via the reconfig mechanism described
below. The master ensures that at most one reconfiguration is taking place at
any time.</p>
<p>See <a class="reference internal" href="master-overview.html#master-service-hierarchy"><span class="std std-ref">Master Organization</span></a> for the structure of the Buildbot service
tree.</p>
<p>To simplify initialization, a reconfiguration is performed immediately on
master startup. As a result, services only need to implement their
configuration handling once, and can use <code class="docutils literal"><span class="pre">startService</span></code> for initialization.</p>
<p>See below for instructions on implementing configuration of common types of
components in Buildbot.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Because Buildbot uses a pure-Python configuration file, it is not possible
to support all forms of reconfiguration. In particular, when the
configuration includes custom subclasses or modules, reconfiguration can
turn up some surprising behaviors due to the dynamic nature of Python. The
reconfig support in Buildbot is intended for "intermediate" uses of the
software, where there are fewer surprises.</p>
</div>
<div class="section" id="reconfigurable-services">
<h3>Reconfigurable Services<a class="headerlink" href="#reconfigurable-services" title="Permalink to this headline">¶</a></h3>
<p>Instances which need to be notified of a change in configuration should be
implemented as Twisted services, and mix in the
<a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin" title="buildbot.config.ReconfigurableServiceMixin"><code class="xref py py-class docutils literal"><span class="pre">ReconfigurableServiceMixin</span></code></a> class, overriding the
<a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin.reconfigService" title="buildbot.config.ReconfigurableServiceMixin.reconfigService"><code class="xref py py-meth docutils literal"><span class="pre">reconfigService</span></code></a> method.</p>
<dl class="class">
<dt id="buildbot.config.ReconfigurableServiceMixin">
<em class="property">class </em><code class="descclassname">buildbot.config.</code><code class="descname">ReconfigurableServiceMixin</code><a class="headerlink" href="#buildbot.config.ReconfigurableServiceMixin" title="Permalink to this definition">¶</a></dt>
<dd><dl class="method">
<dt id="buildbot.config.ReconfigurableServiceMixin.reconfigService">
<code class="descname">reconfigService</code><span class="sig-paren">(</span><em>new_config</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.config.ReconfigurableServiceMixin.reconfigService" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>new_config</strong> (<a class="reference internal" href="#buildbot.config.MasterConfig" title="buildbot.config.MasterConfig"><code class="xref py py-class docutils literal"><span class="pre">MasterConfig</span></code></a>) -- new master configuration</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">Deferred</td>
</tr>
</tbody>
</table>
<p>This method notifies the service that it should make any changes
necessary to adapt to the new configuration values given.</p>
<p>This method will be called automatically after a service is started.</p>
<p>It is generally too late at this point to roll back the
reconfiguration, so if possible any errors should be detected in the
<a class="reference internal" href="#buildbot.config.MasterConfig" title="buildbot.config.MasterConfig"><code class="xref py py-class docutils literal"><span class="pre">MasterConfig</span></code></a> implementation. Errors are handled as best as
possible and communicated back to the top level invocation, but such
errors may leave the master in an inconsistent state.
<a class="reference internal" href="#buildbot.config.ConfigErrors" title="buildbot.config.ConfigErrors"><code class="xref py py-exc docutils literal"><span class="pre">ConfigErrors</span></code></a> exceptions will be displayed appropriately to
the user on startup.</p>
<p>Subclasses should always call the parent class's implementation. For
<code class="xref py py-class docutils literal"><span class="pre">MultiService</span></code> instances, this will call any child services'
<a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin.reconfigService" title="buildbot.config.ReconfigurableServiceMixin.reconfigService"><code class="xref py py-meth docutils literal"><span class="pre">reconfigService</span></code></a> methods, as appropriate. This will be done
sequentially, such that the Deferred from one service must fire before
the next service is reconfigured.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.config.ReconfigurableServiceMixin.priority">
<code class="descname">priority</code><a class="headerlink" href="#buildbot.config.ReconfigurableServiceMixin.priority" title="Permalink to this definition">¶</a></dt>
<dd><p>Child services are reconfigured in order of decreasing priority. The
default priority is 128, so a service that must be reconfigured before
others should be given a higher priority.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="change-sources">
<h3>Change Sources<a class="headerlink" href="#change-sources" title="Permalink to this headline">¶</a></h3>
<p>When reconfiguring, there is no method by which Buildbot can determine that a
new <a class="reference internal" href="../manual/customization.html#buildbot.changes.base.ChangeSource" title="buildbot.changes.base.ChangeSource"><code class="xref py py-class docutils literal"><span class="pre">ChangeSource</span></code></a> represents the same source
as an existing <a class="reference internal" href="../manual/customization.html#buildbot.changes.base.ChangeSource" title="buildbot.changes.base.ChangeSource"><code class="xref py py-class docutils literal"><span class="pre">ChangeSource</span></code></a>, but with
different configuration parameters. As a result, the change source manager
compares the lists of existing and new change sources using equality, stops any
existing sources that are not in the new list, and starts any new change
sources that do not already exist.</p>
<p><a class="reference internal" href="../manual/customization.html#buildbot.changes.base.ChangeSource" title="buildbot.changes.base.ChangeSource"><code class="xref py py-class docutils literal"><span class="pre">ChangeSource</span></code></a> inherits
<a class="reference internal" href="utils.html#buildbot.util.ComparableMixin" title="buildbot.util.ComparableMixin"><code class="xref py py-class docutils literal"><span class="pre">ComparableMixin</span></code></a>, so change sources are compared
based on the attributes described in their <code class="docutils literal"><span class="pre">compare_attrs</span></code>.</p>
<p>If a change source does not make reference to any global configuration
parameters, then there is no need to inherit
<a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin" title="buildbot.config.ReconfigurableServiceMixin"><code class="xref py py-class docutils literal"><span class="pre">ReconfigurableServiceMixin</span></code></a>, as a simple comparison and
<code class="docutils literal"><span class="pre">startService</span></code> and <code class="docutils literal"><span class="pre">stopService</span></code> will be sufficient.</p>
<p>If the change source does make reference to global values, e.g., as default
values for its parameters, then it must inherit
<a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin" title="buildbot.config.ReconfigurableServiceMixin"><code class="xref py py-class docutils literal"><span class="pre">ReconfigurableServiceMixin</span></code></a> to support the case where the global
values change.</p>
</div>
<div class="section" id="schedulers">
<h3>Schedulers<a class="headerlink" href="#schedulers" title="Permalink to this headline">¶</a></h3>
<p>Schedulers have names, so Buildbot can determine whether a scheduler has been
added, removed, or changed during a reconfig. Old schedulers will be stopped,
new schedulers will be started, and both new and existing schedulers will see a
call to <a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin.reconfigService" title="buildbot.config.ReconfigurableServiceMixin.reconfigService"><code class="xref py py-meth docutils literal"><span class="pre">reconfigService</span></code></a>, if such a
method exists. For backward compatibility, schedulers which do not support
reconfiguration will be stopped, and the new scheduler started, when their
configuration changes.</p>
<p>If, during a reconfiguration, a new and old scheduler's fully qualified class
names differ, then the old class will be stopped and the new class started.
This supports the case when a user changes, for example, a Nightly scheduler to
a Periodic scheduler without changing the name.</p>
<p>Because Buildbot uses <code class="xref py py-class docutils literal"><span class="pre">BaseScheduler</span></code>
instances directly in the configuration file, a reconfigured scheduler must
extract its new configuration information from another instance of itself.
<code class="xref py py-class docutils literal"><span class="pre">BaseScheduler</span></code> implements a helper method,
<code class="xref py py-meth docutils literal"><span class="pre">findNewSchedulerInstance</span></code>,
which will return the new instance of the scheduler in the given
<a class="reference internal" href="#buildbot.config.MasterConfig" title="buildbot.config.MasterConfig"><code class="xref py py-class docutils literal"><span class="pre">MasterConfig</span></code></a> object.</p>
<div class="section" id="custom-subclasses">
<h4>Custom Subclasses<a class="headerlink" href="#custom-subclasses" title="Permalink to this headline">¶</a></h4>
<p>Custom subclasses are most often defined directly in the configuration file, or
in a Python module that is reloaded with <code class="docutils literal"><span class="pre">reload</span></code> every time the
configuration is loaded. Because of the dynamic nature of Python, this creates
a new object representing the subclass every time the configuration is loaded
-- even if the class definition has not changed.</p>
<p>Note that if a scheduler's class changes in a reconfig, but the scheduler's
name does not, it will still be treated as a reconfiguration of the existing
scheduler. This means that implementation changes in custom scheduler
subclasses will not be activated with a reconfig. This behavior avoids
stopping and starting such schedulers on every reconfig, but can make
development difficult.</p>
<p>One workaround for this is to change the name of the scheduler before each
reconfig - this will cause the old scheduler to be stopped, and the new
scheduler (with the new name and class) to be started.</p>
</div>
</div>
<div class="section" id="slaves">
<h3>Slaves<a class="headerlink" href="#slaves" title="Permalink to this headline">¶</a></h3>
<p>Similar to schedulers, slaves are specified by name, so new and old
configurations are first compared by name, and any slaves to be added or
removed are noted. Slaves for which the fully-qualified class name has changed
are also added and removed. All slaves have their
<a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin.reconfigService" title="buildbot.config.ReconfigurableServiceMixin.reconfigService"><code class="xref py py-meth docutils literal"><span class="pre">reconfigService</span></code></a> method called.</p>
<p>This method takes care of the basic slave attributes, including changing the PB
registration if necessary. Any subclasses that add configuration parameters
should override <a class="reference internal" href="#buildbot.config.ReconfigurableServiceMixin.reconfigService" title="buildbot.config.ReconfigurableServiceMixin.reconfigService"><code class="xref py py-meth docutils literal"><span class="pre">reconfigService</span></code></a> and
update those parameters. As with Schedulers, because the
<code class="xref py py-class docutils literal"><span class="pre">AbstractBuildSlave</span></code> instance is given directly
in the configuration, on reconfig instances must extract the configuration from
a new instance. The
<code class="xref py py-meth docutils literal"><span class="pre">findNewSlaveInstance</span></code> method
can be used to find the new instance.</p>
</div>
<div class="section" id="user-managers">
<h3>User Managers<a class="headerlink" href="#user-managers" title="Permalink to this headline">¶</a></h3>
<p>Since user managers are rarely used, and their purpose is unclear, they are
always stopped and re-started on every reconfig. This may change in figure
versions.</p>
</div>
<div class="section" id="status-receivers">
<h3>Status Receivers<a class="headerlink" href="#status-receivers" title="Permalink to this headline">¶</a></h3>
<p>At every reconfig, all status listeners are stopped and new versions started.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Buildbot Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../manual/index.html">Buildbot Manual</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Buildbot Development</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="master-overview.html">Master Organization</a></li>
<li class="toctree-l2"><a class="reference internal" href="definitions.html">Definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style.html">Buildbot Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="tests.html">Buildbot's Test Suite</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Configuration</a><ul class="simple">
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="utils.html">Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="database.html">Database</a></li>
<li class="toctree-l2"><a class="reference internal" href="results.html">Build Result Codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="formats.html">File Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="webstatus.html">Web Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="master-slave.html">Master-Slave API</a></li>
<li class="toctree-l2"><a class="reference internal" href="encodings.html">String Encodings</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="plugins-publish.html">How to package Buildbot plugins</a></li>
<li class="toctree-l2"><a class="reference internal" href="classes.html">Classes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes/index.html">Release Notes for Buildbot 0.8.12</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="tests.html" title="Buildbot's Test Suite"
>previous</a> |
<a href="utils.html" title="Utilities"
>next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
>index</a>
</div>
<div role="note" aria-label="source link">
<br/>
<a href="../_sources/developer/config.txt"
rel="nofollow">Show Source</a>
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.1.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
