<!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>Builder 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="Configuration" href="configuration.html" />
<link rel="next" title="Build Factories" href="cfg-buildfactories.html" />
<link rel="prev" title="Buildslaves" href="cfg-buildslaves.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="cfg-buildslaves.html" title="Buildslaves"
accesskey="P">previous</a> |
<a href="cfg-buildfactories.html" title="Build Factories"
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="builder-configuration">
<span id="cfg-builders"></span><span id="id1"></span><h1>Builder Configuration<a class="headerlink" href="#builder-configuration" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#merging-build-requests" id="id4">Merging Build Requests</a></li>
<li><a class="reference internal" href="#prioritizing-builds" id="id5">Prioritizing Builds</a></li>
</ul>
</div>
<p>The <a class="reference internal" href="#cfg-builders" title="builders"><code class="xref bb bb-cfg docutils literal"><span class="pre">builders</span></code></a> configuration key is a list of objects giving configuration for the Builders.
For more information on the function of Builders in Buildbot, see <a class="reference internal" href="concepts.html#builder"><span class="std std-ref">the Concepts chapter</span></a>.
The class definition for the builder configuration is in <code class="file docutils literal"><span class="pre">buildbot.config</span></code>.
In the configuration file, its use looks like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">buildbot.plugins</span> <span class="k">import</span> <span class="n">util</span>
<span class="n">c</span><span class="p">[</span><span class="s1">'builders'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">util</span><span class="o">.</span><span class="n">BuilderConfig</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'quick'</span><span class="p">,</span> <span class="n">slavenames</span><span class="o">=</span><span class="p">[</span><span class="s1">'bot1'</span><span class="p">,</span> <span class="s1">'bot2'</span><span class="p">],</span> <span class="n">factory</span><span class="o">=</span><span class="n">f_quick</span><span class="p">),</span>
<span class="n">util</span><span class="o">.</span><span class="n">BuilderConfig</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'thorough'</span><span class="p">,</span> <span class="n">slavename</span><span class="o">=</span><span class="s1">'bot1'</span><span class="p">,</span> <span class="n">factory</span><span class="o">=</span><span class="n">f_thorough</span><span class="p">),</span>
<span class="p">]</span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">BuilderConfig</span></code> takes the following keyword arguments:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">name</span></code></dt>
<dd>This specifies the Builder's name, which is used in status reports.</dd>
</dl>
<p><code class="docutils literal"><span class="pre">slavename</span></code></p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">slavenames</span></code></dt>
<dd>These arguments specify the buildslave or buildslaves that will be used by this Builder.
All slaves names must appear in the <a class="reference internal" href="cfg-buildslaves.html#cfg-slaves" title="slaves"><code class="xref bb bb-cfg docutils literal"><span class="pre">slaves</span></code></a> configuration parameter.
Each buildslave can accommodate multiple builders.
The <code class="docutils literal"><span class="pre">slavenames</span></code> parameter can be a list of names, while <code class="docutils literal"><span class="pre">slavename</span></code> can specify only one slave.</dd>
<dt><code class="docutils literal"><span class="pre">factory</span></code></dt>
<dd>This is a <code class="xref py py-class docutils literal"><span class="pre">buildbot.process.factory.BuildFactory</span></code> instance which controls how the build is performed by defining the steps in the build.
Full details appear in their own section, <a class="reference internal" href="cfg-buildfactories.html#build-factories"><span class="std std-ref">Build Factories</span></a>.</dd>
</dl>
<p>Other optional keys may be set on each <code class="docutils literal"><span class="pre">BuilderConfig</span></code>:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">builddir</span></code></dt>
<dd>Specifies the name of a subdirectory of the master's basedir in which everything related to this builder will be stored.
This holds build status information.
If not set, this parameter defaults to the builder name, with some characters escaped.
Each builder must have a unique build directory.</dd>
<dt><code class="docutils literal"><span class="pre">slavebuilddir</span></code></dt>
<dd>Specifies the name of a subdirectory (under the slave's configured base directory) in which everything related to this builder will be placed on the buildslave.
This is where checkouts, compiles, and tests are run.
If not set, defaults to <code class="docutils literal"><span class="pre">builddir</span></code>.
If a slave is connected to multiple builders that share the same <code class="docutils literal"><span class="pre">slavebuilddir</span></code>, make sure the slave is set to run one build at a time or ensure this is fine to run multiple builds from the same directory simultaneously.</dd>
<dt><code class="docutils literal"><span class="pre">tags</span></code></dt>
<dd>If provided, this is a list of strings that identifies tags for the builder.
Status clients can limit themselves to a subset of the available tags.
A common use for this is to add new builders to your setup (for a new module, or for a new buildslave) that do not work correctly yet and allow you to integrate them with the active builders.
You can tag these new builders with a <code class="docutils literal"><span class="pre">test</span></code> tag, make your main status clients ignore them, and have only private status clients pick them up.
As soon as they work, you can move them over to the active tag.</dd>
<dt><code class="docutils literal"><span class="pre">nextSlave</span></code></dt>
<dd>If provided, this is a function that controls which slave will be assigned future jobs.
The function is passed two arguments, the <code class="xref py py-class docutils literal"><span class="pre">Builder</span></code> object which is assigning a new job, and a list of <code class="xref py py-class docutils literal"><span class="pre">SlaveBuilder</span></code> objects.
The function should return one of the <code class="xref py py-class docutils literal"><span class="pre">SlaveBuilder</span></code> objects, or <code class="docutils literal"><span class="pre">None</span></code> if none of the available slaves should be used.
As an example, for each <code class="docutils literal"><span class="pre">slave</span></code> in the list, <code class="docutils literal"><span class="pre">slave.slave</span></code> will be a <code class="xref py py-class docutils literal"><span class="pre">BuildSlave</span></code> object, and <code class="docutils literal"><span class="pre">slave.slave.slavename</span></code> is the slave's name.
The function can optionally return a Deferred, which should fire with the same results.</dd>
<dt><code class="docutils literal"><span class="pre">nextBuild</span></code></dt>
<dd>If provided, this is a function that controls which build request will be handled next.
The function is passed two arguments, the <code class="xref py py-class docutils literal"><span class="pre">Builder</span></code> object which is assigning a new job, and a list of <code class="xref py py-class docutils literal"><span class="pre">BuildRequest</span></code> objects of pending builds.
The function should return one of the <code class="xref py py-class docutils literal"><span class="pre">BuildRequest</span></code> objects, or <code class="docutils literal"><span class="pre">None</span></code> if none of the pending builds should be started.
This function can optionally return a Deferred which should fire with the same results.</dd>
<dt><code class="docutils literal"><span class="pre">canStartBuild</span></code></dt>
<dd>If provided, this is a function that can veto whether a particular buildslave should be used for a given build request.
The function is passed three arguments: the <code class="xref py py-class docutils literal"><span class="pre">Builder</span></code>, a <code class="xref py py-class docutils literal"><span class="pre">BuildSlave</span></code>, and a <code class="xref py py-class docutils literal"><span class="pre">BuildRequest</span></code>.
The function should return <code class="docutils literal"><span class="pre">True</span></code> if the combination is acceptable, or <code class="docutils literal"><span class="pre">False</span></code> otherwise.
This function can optionally return a Deferred which should fire with the same results.</dd>
<dt><code class="docutils literal"><span class="pre">locks</span></code></dt>
<dd>This argument specifies a list of locks that apply to this builder; see <a class="reference internal" href="cfg-interlocks.html#interlocks"><span class="std std-ref">Interlocks</span></a>.</dd>
<dt><code class="docutils literal"><span class="pre">env</span></code></dt>
<dd><p class="first">A Builder may be given a dictionary of environment variables in this parameter.
The variables are used in <a class="reference internal" href="cfg-buildsteps.html#step-ShellCommand" title="ShellCommand"><code class="xref bb bb-step docutils literal"><span class="pre">ShellCommand</span></code></a> steps in builds created by this builder.
The environment variables will override anything in the buildslave's environment.
Variables passed directly to a <code class="xref py py-class docutils literal"><span class="pre">ShellCommand</span></code> will override variables of the same name passed to the Builder.</p>
<p>For example, if you have a pool of identical slaves it is often easier to manage variables like <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal"><span class="pre">PATH</span></code> from Buildbot rather than manually editing it inside of the slaves' environment.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="n">factory</span><span class="o">.</span><span class="n">BuildFactory</span>
<span class="n">f</span><span class="o">.</span><span class="n">addStep</span><span class="p">(</span><span class="n">ShellCommand</span><span class="p">(</span>
<span class="n">command</span><span class="o">=</span><span class="p">[</span><span class="s1">'bash'</span><span class="p">,</span> <span class="s1">'./configure'</span><span class="p">]))</span>
<span class="n">f</span><span class="o">.</span><span class="n">addStep</span><span class="p">(</span><span class="n">Compile</span><span class="p">())</span>
<span class="n">c</span><span class="p">[</span><span class="s1">'builders'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">BuilderConfig</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'test'</span><span class="p">,</span> <span class="n">factory</span><span class="o">=</span><span class="n">f</span><span class="p">,</span>
<span class="n">slavenames</span><span class="o">=</span><span class="p">[</span><span class="s1">'slave1'</span><span class="p">,</span> <span class="s1">'slave2'</span><span class="p">,</span> <span class="s1">'slave3'</span><span class="p">,</span> <span class="s1">'slave4'</span><span class="p">],</span>
<span class="n">env</span><span class="o">=</span><span class="p">{</span><span class="s1">'PATH'</span><span class="p">:</span> <span class="s1">'/opt/local/bin:/opt/app/bin:/usr/local/bin:/usr/bin'</span><span class="p">}),</span>
<span class="p">]</span>
</pre></div>
</div>
<p class="last">Unlike most builder configuration arguments, this argument can contain renderables.</p>
</dd>
</dl>
<dl class="docutils" id="index-1">
<dt><code class="docutils literal"><span class="pre">mergeRequests</span></code></dt>
<dd>Specifies how build requests for this builder should be merged.
See <a class="reference internal" href="#merging-build-requests"><span class="std std-ref">Merging Build Requests</span></a>, below.</dd>
</dl>
<dl class="docutils" id="index-2">
<dt><code class="docutils literal"><span class="pre">properties</span></code></dt>
<dd>A builder may be given a dictionary of <a class="reference internal" href="concepts.html#build-properties"><span class="std std-ref">Build Properties</span></a> specific for this builder in this parameter.
Those values can be used later on like other properties. <a class="reference internal" href="cfg-properties.html#interpolate"><span class="std std-ref">Interpolate</span></a>.</dd>
<dt><code class="docutils literal"><span class="pre">description</span></code></dt>
<dd>A builder may be given an arbitrary description, which will show up in the web status on the builder's page.</dd>
</dl>
<div class="section" id="merging-build-requests">
<span id="index-3"></span><span id="id2"></span><h2><a class="toc-backref" href="#id4">Merging Build Requests</a><a class="headerlink" href="#merging-build-requests" title="Permalink to this headline">¶</a></h2>
<p>When more than one build request is available for a builder, Buildbot can "merge" the requests into a single build.
This is desirable when build requests arrive more quickly than the available slaves can satisfy them, but has the drawback that separate results for each build are not available.</p>
<p>Requests are only candidated for a merge if both requests have exactly the same <a class="reference internal" href="concepts.html#attr-codebase"><span class="std std-ref">codebases</span></a>.</p>
<p>This behavior can be controlled globally, using the <a class="reference internal" href="cfg-global.html#cfg-mergeRequests" title="mergeRequests"><code class="xref bb bb-cfg docutils literal"><span class="pre">mergeRequests</span></code></a> parameter, and on a per-<code class="xref py py-class docutils literal"><span class="pre">Builder</span></code> basis, using the <code class="docutils literal"><span class="pre">mergeRequests</span></code> argument to the <code class="xref py py-class docutils literal"><span class="pre">Builder</span></code> configuration.
If <code class="docutils literal"><span class="pre">mergeRequests</span></code> is given, it completely overrides the global configuration.</p>
<p>For either configuration parameter, a value of <code class="docutils literal"><span class="pre">True</span></code> (the default) causes buildbot to merge BuildRequests that have "compatible" source stamps.
Source stamps are compatible if:</p>
<ul class="simple">
<li>their codebase, branch, project, and repository attributes match exactly;</li>
<li>neither source stamp has a patch (e.g., from a try scheduler); and</li>
<li>either both source stamps are associated with changes, or neither ar associated with changes but they have matching revisions.</li>
</ul>
<p>This algorithm is implemented by the <code class="xref py py-class docutils literal"><span class="pre">SourceStamp</span></code> method <code class="xref py py-func docutils literal"><span class="pre">canBeMergedWith</span></code>.</p>
<p>A configuration value of <code class="docutils literal"><span class="pre">False</span></code> indicates that requests should never be merged.</p>
<p>The configuration value can also be a callable, specifying a custom merging function.
See <a class="reference internal" href="customization.html#merge-request-functions"><span class="std std-ref">Merge Request Functions</span></a> for details.</p>
</div>
<div class="section" id="prioritizing-builds">
<span id="index-4"></span><span id="id3"></span><h2><a class="toc-backref" href="#id5">Prioritizing Builds</a><a class="headerlink" href="#prioritizing-builds" title="Permalink to this headline">¶</a></h2>
<p>The <code class="xref py py-class docutils literal"><span class="pre">BuilderConfig</span></code> parameter <code class="docutils literal"><span class="pre">nextBuild</span></code> can be use to prioritize build requests within a builder.
Note that this is orthogonal to <a class="reference internal" href="cfg-global.html#prioritizing-builders"><span class="std std-ref">Prioritizing Builders</span></a>, which controls the order in which builders are called on to start their builds.
The details of writing such a function are in <a class="reference internal" href="customization.html#build-priority-functions"><span class="std std-ref">Build Priority Functions</span></a>.</p>
<p>Such a function can be provided to the BuilderConfig as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">pickNextBuild</span><span class="p">(</span><span class="n">builder</span><span class="p">,</span> <span class="n">requests</span><span class="p">):</span>
<span class="o">...</span>
<span class="n">c</span><span class="p">[</span><span class="s1">'builders'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">BuilderConfig</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'test'</span><span class="p">,</span> <span class="n">factory</span><span class="o">=</span><span class="n">f</span><span class="p">,</span>
<span class="n">nextBuild</span><span class="o">=</span><span class="n">pickNextBuild</span><span class="p">,</span>
<span class="n">slavenames</span><span class="o">=</span><span class="p">[</span><span class="s1">'slave1'</span><span class="p">,</span> <span class="s1">'slave2'</span><span class="p">,</span> <span class="s1">'slave3'</span><span class="p">,</span> <span class="s1">'slave4'</span><span class="p">]),</span>
<span class="p">]</span>
</pre></div>
</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 current"><a class="reference internal" href="index.html">Buildbot Manual</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html">Concepts</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="configuration.html">Configuration</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="cfg-intro.html">Configuring Buildbot</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-global.html">Global Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-changesources.html">Change Sources</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-schedulers.html">Schedulers</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-buildslaves.html">Buildslaves</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Builder Configuration</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="cfg-buildfactories.html">Build Factories</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-properties.html">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-buildsteps.html">Build Steps</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-interlocks.html">Interlocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="cfg-statustargets.html">Status Targets</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="customization.html">Customization</a></li>
<li class="toctree-l2"><a class="reference internal" href="new-style-steps.html">New-Style Build Steps</a></li>
<li class="toctree-l2"><a class="reference internal" href="cmdline.html">Command-line Tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="resources.html">Resources</a></li>
<li class="toctree-l2"><a class="reference internal" href="optimization.html">Optimization</a></li>
<li class="toctree-l2"><a class="reference internal" href="plugins.html">Plugin Infrastructure in Buildbot</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../developer/index.html">Buildbot Development</a></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="cfg-buildslaves.html" title="Buildslaves"
>previous</a> |
<a href="cfg-buildfactories.html" title="Build Factories"
>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/manual/cfg-builders.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>
