<!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>Build Factories — 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="Properties" href="cfg-properties.html" />
<link rel="prev" title="Builder Configuration" href="cfg-builders.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-builders.html" title="Builder Configuration"
accesskey="P">previous</a> |
<a href="cfg-properties.html" title="Properties"
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="build-factories">
<span id="id1"></span><h1>Build Factories<a class="headerlink" href="#build-factories" title="Permalink to this headline">¶</a></h1>
<p>Each Builder is equipped with a <code class="docutils literal"><span class="pre">build</span> <span class="pre">factory</span></code>, which is defines the steps used to perform that particular type of build.
This factory is created in the configuration file, and attached to a Builder through the <code class="docutils literal"><span class="pre">factory</span></code> element of its dictionary.</p>
<p>The steps used by these builds are defined in the next section, <a class="reference internal" href="cfg-buildsteps.html#build-steps"><span class="std std-ref">Build Steps</span></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Build factories are used with builders, and are not added directly to the buildmaster configuration dictionary.</p>
</div>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#defining-a-build-factory" id="id9">Defining a Build Factory</a></li>
<li><a class="reference internal" href="#predefined-build-factories" id="id10">Predefined Build Factories</a></li>
</ul>
</div>
<span class="target" id="buildfactory"></span><div class="section" id="defining-a-build-factory">
<span id="index-0"></span><h2><a class="toc-backref" href="#id9">Defining a Build Factory</a><a class="headerlink" href="#defining-a-build-factory" title="Permalink to this headline">¶</a></h2>
<p>A <code class="xref py py-class docutils literal"><span class="pre">BuildFactory</span></code> defines the steps that every build will follow.
Think of it as a glorified script.
For example, a build factory which consists of an SVN checkout followed by a <code class="docutils literal"><span class="pre">make</span> <span class="pre">build</span></code> would be configured as follows:</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="p">,</span> <span class="n">steps</span>
<span class="n">f</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">BuildFactory</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">steps</span><span class="o">.</span><span class="n">SVN</span><span class="p">(</span><span class="n">svnurl</span><span class="o">=</span><span class="s2">"http://.."</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">"incremental"</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">steps</span><span class="o">.</span><span class="n">Compile</span><span class="p">(</span><span class="n">command</span><span class="o">=</span><span class="p">[</span><span class="s2">"make"</span><span class="p">,</span> <span class="s2">"build"</span><span class="p">]))</span>
</pre></div>
</div>
<p>This factory would then be attached to one builder (or several, if desired):</p>
<div class="highlight-default"><div class="highlight"><pre><span></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="n">append</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">'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</span><span class="p">))</span>
</pre></div>
</div>
<p>It is also possible to pass a list of steps into the <code class="xref py py-class docutils literal"><span class="pre">BuildFactory</span></code> when it is created.
Using <code class="xref py py-meth docutils literal"><span class="pre">addStep</span></code> is usually simpler, but there are cases where is is more convenient to create the list of steps ahead of time, perhaps using some Python tricks to generate the steps.</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">steps</span><span class="p">,</span> <span class="n">util</span>
<span class="n">all_steps</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">steps</span><span class="o">.</span><span class="n">CVS</span><span class="p">(</span><span class="n">cvsroot</span><span class="o">=</span><span class="n">CVSROOT</span><span class="p">,</span> <span class="n">cvsmodule</span><span class="o">=</span><span class="s2">"project"</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">"update"</span><span class="p">),</span>
<span class="n">steps</span><span class="o">.</span><span class="n">Compile</span><span class="p">(</span><span class="n">command</span><span class="o">=</span><span class="p">[</span><span class="s2">"make"</span><span class="p">,</span> <span class="s2">"build"</span><span class="p">]),</span>
<span class="p">]</span>
<span class="n">f</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">BuildFactory</span><span class="p">(</span><span class="n">all_steps</span><span class="p">)</span>
</pre></div>
</div>
<p>Finally, you can also add a sequence of steps all at once:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">f</span><span class="o">.</span><span class="n">addSteps</span><span class="p">(</span><span class="n">all_steps</span><span class="p">)</span>
</pre></div>
</div>
<div class="section" id="attributes">
<h3>Attributes<a class="headerlink" href="#attributes" title="Permalink to this headline">¶</a></h3>
<p>The following attributes can be set on a build factory after it is created, e.g.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">BuildFactory</span><span class="p">()</span>
<span class="n">f</span><span class="o">.</span><span class="n">useProgress</span> <span class="o">=</span> <span class="kc">False</span>
</pre></div>
</div>
<dl class="docutils">
<dt><code class="xref py py-attr docutils literal"><span class="pre">useProgress</span></code></dt>
<dd>(defaults to <code class="docutils literal"><span class="pre">True</span></code>): if <code class="docutils literal"><span class="pre">True</span></code>, the buildmaster keeps track of how long each step takes, so it can provide estimates of how long future builds will take.
If builds are not expected to take a consistent amount of time (such as incremental builds in which a random set of files are recompiled or tested each time), this should be set to <code class="docutils literal"><span class="pre">False</span></code> to inhibit progress-tracking.</dd>
<dt><code class="xref py py-attr docutils literal"><span class="pre">workdir</span></code></dt>
<dd><p class="first">(defaults to 'build'): workdir given to every build step created by this factory as default.
The workdir can be overridden in a build step definition.</p>
<p class="last">If this attribute is set to a string, that string will be used for constructing the workdir (buildslave base + builder builddir + workdir).
The attribute can also be a Python callable, for more complex cases, as described in <a class="reference internal" href="customization.html#factory-workdir-functions"><span class="std std-ref">Factory Workdir Functions</span></a>.</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="predefined-build-factories">
<h2><a class="toc-backref" href="#id10">Predefined Build Factories</a><a class="headerlink" href="#predefined-build-factories" title="Permalink to this headline">¶</a></h2>
<p>Buildbot includes a few predefined build factories that perform common build sequences.
In practice, these are rarely used, as every site has slightly different requirements, but the source for these factories may provide examples for implementation of those requirements.</p>
<span class="target" id="gnuautoconf"></span><div class="section" id="index-1">
<span id="id2"></span><h3>GNUAutoconf<a class="headerlink" href="#index-1" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="buildbot.process.factory.GNUAutoconf">
<em class="property">class </em><code class="descclassname">buildbot.process.factory.</code><code class="descname">GNUAutoconf</code><a class="headerlink" href="#buildbot.process.factory.GNUAutoconf" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p><a class="reference external" href="http://www.gnu.org/software/autoconf/">GNU Autoconf</a> is a software portability tool, intended to make it possible to write programs in C (and other languages) which will run on a variety of UNIX-like systems.
Most GNU software is built using autoconf.
It is frequently used in combination with GNU automake.
These tools both encourage a build process which usually looks like this:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>% <span class="nv">CONFIG_ENV</span><span class="o">=</span>foo ./configure --with-flags
% make all
% make check
<span class="c1"># make install</span>
</pre></div>
</div>
<p>(except of course the Buildbot always skips the <code class="docutils literal"><span class="pre">make</span> <span class="pre">install</span></code> part).</p>
<p>The Buildbot's <a class="reference internal" href="#buildbot.process.factory.GNUAutoconf" title="buildbot.process.factory.GNUAutoconf"><code class="xref py py-class docutils literal"><span class="pre">buildbot.process.factory.GNUAutoconf</span></code></a> factory is designed to build projects which use GNU autoconf and/or automake.
The configuration environment variables, the configure flags, and command lines used for the compile and test are all configurable, in general the default values will be suitable.</p>
<p>Example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">GNUAutoconf</span><span class="p">(</span><span class="n">source</span><span class="o">=</span><span class="n">steps</span><span class="o">.</span><span class="n">SVN</span><span class="p">(</span><span class="n">svnurl</span><span class="o">=</span><span class="n">URL</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">"copy"</span><span class="p">),</span>
<span class="n">flags</span><span class="o">=</span><span class="p">[</span><span class="s2">"--disable-nls"</span><span class="p">])</span>
</pre></div>
</div>
<p>Required Arguments:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">source</span></code></dt>
<dd>This argument must be a step specification tuple that provides a BuildStep to generate the source tree.</dd>
</dl>
<p>Optional Arguments:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">configure</span></code></dt>
<dd>The command used to configure the tree.
Defaults to <strong class="command">./configure</strong>.
Accepts either a string or a list of shell argv elements.</dd>
<dt><code class="docutils literal"><span class="pre">configureEnv</span></code></dt>
<dd>The environment used for the initial configuration step.
This accepts a dictionary which will be merged into the buildslave's normal environment.
This is commonly used to provide things like <code class="docutils literal"><span class="pre">CFLAGS="-O2</span> <span class="pre">-g"</span></code> (to turn off debug symbols during the compile).
Defaults to an empty dictionary.</dd>
<dt><code class="docutils literal"><span class="pre">configureFlags</span></code></dt>
<dd>A list of flags to be appended to the argument list of the configure command.
This is commonly used to enable or disable specific features of the autoconf-controlled package, like <code class="docutils literal"><span class="pre">["--without-x"]</span></code> to disable windowing support.
Defaults to an empty list.</dd>
<dt><code class="docutils literal"><span class="pre">reconf</span></code></dt>
<dd>use autoreconf to generate the ./configure file, set to True to use a buildbot default autoreconf command, or define the command for the ShellCommand.</dd>
<dt><code class="docutils literal"><span class="pre">compile</span></code></dt>
<dd>this is a shell command or list of argv values which is used to actually compile the tree.
It defaults to <code class="docutils literal"><span class="pre">make</span> <span class="pre">all</span></code>.
If set to <code class="docutils literal"><span class="pre">None</span></code>, the compile step is skipped.</dd>
<dt><code class="docutils literal"><span class="pre">test</span></code></dt>
<dd>this is a shell command or list of argv values which is used to run the tree's self-tests.
It defaults to <code class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></code>.
If set to None, the test step is skipped.</dd>
<dt><code class="docutils literal"><span class="pre">distcheck</span></code></dt>
<dd>this is a shell command or list of argv values which is used to run the packaging test.
It defaults to <code class="docutils literal"><span class="pre">make</span> <span class="pre">distcheck</span></code>.
If set to None, the test step is skipped.</dd>
</dl>
<span class="target" id="basicbuildfactory"></span></div>
<div class="section" id="index-2">
<span id="id3"></span><h3>BasicBuildFactory<a class="headerlink" href="#index-2" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="buildbot.process.factory.BasicBuildFactory">
<em class="property">class </em><code class="descclassname">buildbot.process.factory.</code><code class="descname">BasicBuildFactory</code><a class="headerlink" href="#buildbot.process.factory.BasicBuildFactory" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This is a subclass of <code class="xref py py-class docutils literal"><span class="pre">GNUAutoconf</span></code> which assumes the source is in CVS, and uses <code class="docutils literal"><span class="pre">mode='full'</span></code> and <code class="docutils literal"><span class="pre">method='clobber'</span></code> to always build from a clean working copy.</p>
<span class="target" id="basicsvn"></span></div>
<div class="section" id="index-3">
<span id="id4"></span><h3>BasicSVN<a class="headerlink" href="#index-3" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="buildbot.process.factory.BasicSVN">
<em class="property">class </em><code class="descclassname">buildbot.process.factory.</code><code class="descname">BasicSVN</code><a class="headerlink" href="#buildbot.process.factory.BasicSVN" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>This class is similar to <code class="xref py py-class docutils literal"><span class="pre">QuickBuildFactory</span></code>, but uses SVN instead of CVS.</p>
<span class="target" id="quickbuildfactory"></span></div>
<div class="section" id="index-4">
<span id="id5"></span><h3>QuickBuildFactory<a class="headerlink" href="#index-4" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="buildbot.process.factory.QuickBuildFactory">
<em class="property">class </em><code class="descclassname">buildbot.process.factory.</code><code class="descname">QuickBuildFactory</code><a class="headerlink" href="#buildbot.process.factory.QuickBuildFactory" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>The <code class="xref py py-class docutils literal"><span class="pre">QuickBuildFactory</span></code> class is a subclass of <code class="xref py py-class docutils literal"><span class="pre">GNUAutoconf</span></code> which assumes the source is in CVS, and uses <code class="docutils literal"><span class="pre">mode='incremental'</span></code> to get incremental updates.</p>
<p>The difference between a <cite>full build</cite> and a <cite>quick build</cite> is that quick builds are generally done incrementally, starting with the tree where the previous build was performed.
That simply means that the source-checkout step should be given a <code class="docutils literal"><span class="pre">mode='incremental'</span></code> flag, to do the source update in-place.</p>
<p>In addition to that, this class sets the <code class="xref py py-attr docutils literal"><span class="pre">useProgress</span></code> flag to <code class="docutils literal"><span class="pre">False</span></code>.
Incremental builds will (or at least the ought to) compile as few files as necessary, so they will take an unpredictable amount of time to run.
Therefore it would be misleading to claim to predict how long the build will take.</p>
<p>This class is probably not of use to new projects.</p>
<span class="target" id="factory-cpan"></span></div>
<div class="section" id="cpan">
<span id="index-5"></span><h3>CPAN<a class="headerlink" href="#cpan" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="buildbot.process.factory.CPAN">
<em class="property">class </em><code class="descclassname">buildbot.process.factory.</code><code class="descname">CPAN</code><a class="headerlink" href="#buildbot.process.factory.CPAN" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Most Perl modules available from the <a class="reference external" href="http://www.cpan.org/">CPAN</a> archive use the <code class="docutils literal"><span class="pre">MakeMaker</span></code> module to provide configuration, build, and test services.
The standard build routine for these modules looks like:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>% perl Makefile.PL
% make
% make <span class="nb">test</span>
<span class="c1"># make install</span>
</pre></div>
</div>
<p>(except again Buildbot skips the install step)</p>
<p>Buildbot provides a <code class="xref py py-class docutils literal"><span class="pre">CPAN</span></code> factory to compile and test these projects.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">source</span></code></dt>
<dd>(required): A step specification tuple, like that used by <code class="xref py py-class docutils literal"><span class="pre">GNUAutoconf</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">perl</span></code></dt>
<dd>A string which specifies the <strong class="command">perl</strong> executable to use.
Defaults to just <strong class="command">perl</strong>.</dd>
</dl>
<span class="target" id="distutils"></span></div>
<div class="section" id="index-6">
<span id="id7"></span><h3>Distutils<a class="headerlink" href="#index-6" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="buildbot.process.factory.Distutils">
<em class="property">class </em><code class="descclassname">buildbot.process.factory.</code><code class="descname">Distutils</code><a class="headerlink" href="#buildbot.process.factory.Distutils" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Most Python modules use the <code class="docutils literal"><span class="pre">distutils</span></code> package to provide configuration and build services.
The standard build process looks like:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>% python ./setup.py build
% python ./setup.py install
</pre></div>
</div>
<p>Unfortunately, although Python provides a standard unit-test framework named <code class="docutils literal"><span class="pre">unittest</span></code>, to the best of my knowledge <code class="docutils literal"><span class="pre">distutils</span></code> does not provide a standardized target to run such unit tests.
(Please let me know if I'm wrong, and I will update this factory.)</p>
<p>The <code class="xref py py-class docutils literal"><span class="pre">Distutils</span></code> factory provides support for running the build part of this process.
It accepts the same <code class="docutils literal"><span class="pre">source=</span></code> parameter as the other build factories.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">source</span></code></dt>
<dd>(required): A step specification tuple, like that used by <code class="xref py py-class docutils literal"><span class="pre">GNUAutoconf</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">python</span></code></dt>
<dd>A string which specifies the <strong class="command">python</strong> executable to use.
Defaults to just <strong class="command">python</strong>.</dd>
<dt><code class="docutils literal"><span class="pre">test</span></code></dt>
<dd>Provides a shell command which runs unit tests.
This accepts either a string or a list.
The default value is <code class="docutils literal"><span class="pre">None</span></code>, which disables the test step (since there is no common default command to run unit tests in distutils modules).</dd>
</dl>
<span class="target" id="trial"></span></div>
<div class="section" id="index-7">
<span id="id8"></span><h3>Trial<a class="headerlink" href="#index-7" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="buildbot.process.factory.Trial">
<em class="property">class </em><code class="descclassname">buildbot.process.factory.</code><code class="descname">Trial</code><a class="headerlink" href="#buildbot.process.factory.Trial" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>Twisted provides a unit test tool named <strong class="command">trial</strong> which provides a few improvements over Python's built-in <code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code> module.
Many python projects which use Twisted for their networking or application services also use trial for their unit tests.
These modules are usually built and tested with something like the following:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>% python ./setup.py build
% <span class="nv">PYTHONPATH</span><span class="o">=</span>build/lib.linux-i686-2.3 trial -v PROJECTNAME.test
% python ./setup.py install
</pre></div>
</div>
<p>Unfortunately, the <code class="file docutils literal"><span class="pre">build/lib</span></code> directory into which the built/copied <code class="docutils literal"><span class="pre">.py</span></code> files are placed is actually architecture-dependent, and I do not yet know of a simple way to calculate its value.
For many projects it is sufficient to import their libraries <cite>in place</cite> from the tree's base directory (<code class="docutils literal"><span class="pre">PYTHONPATH=.</span></code>).</p>
<p>In addition, the <code class="samp docutils literal"><em><span class="pre">PROJECTNAME</span></em></code> value where the test files are located is project-dependent: it is usually just the project's top-level library directory, as common practice suggests the unit test files are put in the <code class="xref py py-mod docutils literal"><span class="pre">test</span></code> sub-module.
This value cannot be guessed, the <code class="xref py py-class docutils literal"><span class="pre">Trial</span></code> class must be told where to find the test files.</p>
<p>The <code class="xref py py-class docutils literal"><span class="pre">Trial</span></code> class provides support for building and testing projects which use distutils and trial.
If the test module name is specified, trial will be invoked.
The library path used for testing can also be set.</p>
<p>One advantage of trial is that the Buildbot happens to know how to parse trial output, letting it identify which tests passed and which ones failed.
The Buildbot can then provide fine-grained reports about how many tests have failed, when individual tests fail when they had been passing previously, etc.</p>
<p>Another feature of trial is that you can give it a series of source <code class="docutils literal"><span class="pre">.py</span></code> files, and it will search them for special <code class="docutils literal"><span class="pre">test-case-name</span></code> tags that indicate which test cases provide coverage for that file.
Trial can then run just the appropriate tests.
This is useful for quick builds, where you want to only run the test cases that cover the changed functionality.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">testpath</span></code></dt>
<dd>Provides a directory to add to <span class="target" id="index-8"></span><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONPATH</span></code> when running the unit tests, if tests are being run.
Defaults to <code class="docutils literal"><span class="pre">.</span></code> to include the project files in-place.
The generated build library is frequently architecture-dependent, but may simply be <code class="file docutils literal"><span class="pre">build/lib</span></code> for pure-python modules.</dd>
<dt><code class="docutils literal"><span class="pre">python</span></code></dt>
<dd>which Python executable to use.
This list will form the start of the <cite>argv</cite> array that will launch trial.
If you use this, you should set <code class="docutils literal"><span class="pre">trial</span></code> to an explicit path (like <code class="file docutils literal"><span class="pre">/usr/bin/trial</span></code> or <code class="file docutils literal"><span class="pre">./bin/trial</span></code>).
The parameter defaults to <code class="docutils literal"><span class="pre">None</span></code>, which leaves it out entirely (running <code class="docutils literal"><span class="pre">trial</span> <span class="pre">args</span></code> instead of <code class="docutils literal"><span class="pre">python</span> <span class="pre">./bin/trial</span> <span class="pre">args</span></code>).
Likely values are <code class="docutils literal"><span class="pre">['python']</span></code>, <code class="docutils literal"><span class="pre">['python2.2']</span></code>, or <code class="docutils literal"><span class="pre">['python',</span> <span class="pre">'-Wall']</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">trial</span></code></dt>
<dd>provides the name of the <strong class="command">trial</strong> command.
It is occasionally useful to use an alternate executable, such as <strong class="command">trial2.2</strong> which might run the tests under an older version of Python.
Defaults to <strong class="command">trial</strong>.</dd>
<dt><code class="docutils literal"><span class="pre">trialMode</span></code></dt>
<dd>a list of arguments to pass to trial, specifically to set the reporting mode.
This defaults to <code class="docutils literal"><span class="pre">['--reporter=bwverbose']</span></code>, which only works for Twisted-2.1.0 and later.</dd>
<dt><code class="docutils literal"><span class="pre">trialArgs</span></code></dt>
<dd>a list of arguments to pass to trial, available to turn on any extra flags you like.
Defaults to <code class="docutils literal"><span class="pre">[]</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">tests</span></code></dt>
<dd>Provides a module name or names which contain the unit tests for this project.
Accepts a string, typically <code class="samp docutils literal"><em><span class="pre">PROJECTNAME</span></em><span class="pre">.test</span></code>, or a list of strings.
Defaults to <code class="docutils literal"><span class="pre">None</span></code>, indicating that no tests should be run.
You must either set this or <code class="docutils literal"><span class="pre">testChanges</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">testChanges</span></code></dt>
<dd>if <code class="docutils literal"><span class="pre">True</span></code>, ignore the <code class="docutils literal"><span class="pre">tests</span></code> parameter and instead ask the Build for all the files that make up the Changes going into this build.
Pass these filenames to trial and ask it to look for test-case-name tags, running just the tests necessary to cover the changes.</dd>
<dt><code class="docutils literal"><span class="pre">recurse</span></code></dt>
<dd>If <code class="docutils literal"><span class="pre">True</span></code>, tells Trial (with the <code class="docutils literal"><span class="pre">--recurse</span></code> argument) to look in all subdirectories for additional test cases.</dd>
<dt><code class="docutils literal"><span class="pre">reactor</span></code></dt>
<dd>which reactor to use, like 'gtk' or 'java'.
If not provided, the Twisted's usual platform-dependent default is used.</dd>
<dt><code class="docutils literal"><span class="pre">randomly</span></code></dt>
<dd>If <code class="docutils literal"><span class="pre">True</span></code>, tells Trial (with the <code class="docutils literal"><span class="pre">--random=0</span></code> argument) to run the test cases in random order, which sometimes catches subtle inter-test dependency bugs.
Defaults to <code class="docutils literal"><span class="pre">False</span></code>.</dd>
</dl>
<p>The step can also take any of the <code class="xref py py-class docutils literal"><span class="pre">ShellCommand</span></code> arguments, e.g., <code class="xref py py-attr docutils literal"><span class="pre">haltOnFailure</span></code>.</p>
<p>Unless one of <code class="docutils literal"><span class="pre">tests</span></code> or <code class="docutils literal"><span class="pre">testChanges</span></code> are set, the step will generate an exception.</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 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"><a class="reference internal" href="cfg-builders.html">Builder Configuration</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Build Factories</a><ul class="simple">
</ul>
</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-builders.html" title="Builder Configuration"
>previous</a> |
<a href="cfg-properties.html" title="Properties"
>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-buildfactories.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>
