<!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>BuildFactory — Buildbot 0.8.9 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.9',
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.9 documentation" href="../index.html" />
<link rel="up" title="Classes" href="classes.html" />
<link rel="next" title="BuildSetSummaryNotifierMixin" href="cls-buildsetsummarynotifiermixin.html" />
<link rel="prev" title="Classes" href="classes.html" />
</head>
<body>
<div class="header-wrapper">
<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.9 documentation</a></div>
<div class="rel">
<a href="classes.html" title="Classes"
accesskey="P">previous</a> |
<a href="cls-buildsetsummarynotifiermixin.html" title="BuildSetSummaryNotifierMixin"
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">
<div class="section" id="buildfactory">
<h1>BuildFactory<a class="headerlink" href="#buildfactory" title="Permalink to this headline">¶</a></h1>
<div class="section" id="buildfactory-implementation-note">
<h2>BuildFactory Implementation Note<a class="headerlink" href="#buildfactory-implementation-note" title="Permalink to this headline">¶</a></h2>
<p>The default <tt class="xref py py-class docutils literal"><span class="pre">BuildFactory</span></tt>, provided in the
<tt class="xref py py-mod docutils literal"><span class="pre">buildbot.process.factory</span></tt> module, contains an internal list of
<cite>BuildStep specifications</cite>: a list of <tt class="docutils literal"><span class="pre">(step_class,</span> <span class="pre">kwargs)</span></tt>
tuples for each. These specification tuples are constructed when the
config file is read, by asking the instances passed to <tt class="xref py py-meth docutils literal"><span class="pre">addStep</span></tt>
for their subclass and arguments.</p>
<p>To support config files from buildbot-0.7.5 and earlier,
<tt class="xref py py-meth docutils literal"><span class="pre">addStep</span></tt> also accepts the <tt class="docutils literal"><span class="pre">f.addStep(shell.Compile,</span>
<span class="pre">command=["make","build"])</span></tt> form, although its use is discouraged
because then the <tt class="docutils literal"><span class="pre">Compile</span></tt> step doesn't get to validate or
complain about its arguments until build time. The modern
pass-by-instance approach allows this validation to occur while the
config file is being loaded, where the admin has a better chance of
noticing problems.</p>
<p>When asked to create a <tt class="xref py py-class docutils literal"><span class="pre">Build</span></tt>, the <tt class="xref py py-class docutils literal"><span class="pre">BuildFactory</span></tt> puts a copy of
the list of step specifications into the new <tt class="xref py py-class docutils literal"><span class="pre">Build</span></tt> object. When the
<tt class="xref py py-class docutils literal"><span class="pre">Build</span></tt> is actually started, these step specifications are used to
create the actual set of <tt class="xref py py-class docutils literal"><span class="pre">BuildStep</span></tt>s, which are then executed one at a
time. This serves to give each Build an independent copy of each step.</p>
<p>Each step can affect the build process in the following ways:</p>
<blockquote>
<div><ul class="simple">
<li>If the step's <tt class="xref py py-attr docutils literal"><span class="pre">haltOnFailure</span></tt> attribute is <tt class="docutils literal"><span class="pre">True</span></tt>, then a failure
in the step (i.e. if it completes with a result of <tt class="docutils literal"><span class="pre">FAILURE</span></tt>) will cause
the whole build to be terminated immediately: no further steps will be
executed, with the exception of steps with <tt class="xref py py-attr docutils literal"><span class="pre">alwaysRun</span></tt> set to
<tt class="docutils literal"><span class="pre">True</span></tt>. <tt class="xref py py-attr docutils literal"><span class="pre">haltOnFailure</span></tt> is useful for setup steps upon which the
rest of the build depends: if the CVS checkout or <strong class="command">./configure</strong>
process fails, there is no point in trying to compile or test the
resulting tree.</li>
<li>If the step's <tt class="xref py py-attr docutils literal"><span class="pre">alwaysRun</span></tt> attribute is <tt class="docutils literal"><span class="pre">True</span></tt>, then it will always
be run, regardless of if previous steps have failed. This is useful
for cleanup steps that should always be run to return the build
directory or build slave into a good state.</li>
<li>If the <tt class="xref py py-attr docutils literal"><span class="pre">flunkOnFailure</span></tt> or <tt class="xref py py-attr docutils literal"><span class="pre">flunkOnWarnings</span></tt> flag is set,
then a result of <tt class="docutils literal"><span class="pre">FAILURE</span></tt> or <tt class="docutils literal"><span class="pre">WARNINGS</span></tt> will mark the build as a whole as
<tt class="docutils literal"><span class="pre">FAILED</span></tt>. However, the remaining steps will still be executed. This is
appropriate for things like multiple testing steps: a failure in any
one of them will indicate that the build has failed, however it is
still useful to run them all to completion.</li>
<li>Similarly, if the <tt class="xref py py-attr docutils literal"><span class="pre">warnOnFailure</span></tt> or <tt class="xref py py-attr docutils literal"><span class="pre">warnOnWarnings</span></tt> flag
is set, then a result of <tt class="docutils literal"><span class="pre">FAILURE</span></tt> or <tt class="docutils literal"><span class="pre">WARNINGS</span></tt> will mark the build as
having <tt class="docutils literal"><span class="pre">WARNINGS</span></tt>, and the remaining steps will still be executed. This
may be appropriate for certain kinds of optional build or test steps.
For example, a failure experienced while building documentation files
should be made visible with a <tt class="docutils literal"><span class="pre">WARNINGS</span></tt> result but not be serious
enough to warrant marking the whole build with a <tt class="docutils literal"><span class="pre">FAILURE</span></tt>.</li>
</ul>
</div></blockquote>
<p>In addition, each <tt class="xref py py-class docutils literal"><span class="pre">Step</span></tt> produces its own results, may create logfiles,
etc. However only the flags described above have any effect on the
build as a whole.</p>
<p>The pre-defined <tt class="xref py py-class docutils literal"><span class="pre">BuildStep</span></tt>s like <tt class="xref py py-class docutils literal"><span class="pre">CVS</span></tt> and <tt class="xref py py-class docutils literal"><span class="pre">Compile</span></tt> have
reasonably appropriate flags set on them already. For example, without
a source tree there is no point in continuing the build, so the
<tt class="xref py py-class docutils literal"><span class="pre">CVS</span></tt> class has the <tt class="xref py py-attr docutils literal"><span class="pre">haltOnFailure</span></tt> flag set to <tt class="docutils literal"><span class="pre">True</span></tt>. Look
in <tt class="file docutils literal"><span class="pre">buildbot/steps/*.py</span></tt> to see how the other <tt class="xref py py-class docutils literal"><span class="pre">Step</span></tt>s are
marked.</p>
<p>Each <tt class="xref py py-class docutils literal"><span class="pre">Step</span></tt> is created with an additional <tt class="docutils literal"><span class="pre">workdir</span></tt> argument that
indicates where its actions should take place. This is specified as a
subdirectory of the slave builder's base directory, with a default
value of <tt class="file docutils literal"><span class="pre">build</span></tt>. This is only implemented as a step argument (as
opposed to simply being a part of the base directory) because the
CVS/SVN steps need to perform their checkouts from the parent
directory.</p>
</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"><a class="reference internal" href="config.html">Configuration</a></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 current"><a class="reference internal" href="classes.html">Classes</a><ul class="current">
<li class="toctree-l3 current"><a class="current reference internal" href="">BuildFactory</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="cls-buildsetsummarynotifiermixin.html">BuildSetSummaryNotifierMixin</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-remotecommands.html">RemoteCommands</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-buildsteps.html">BuildSteps</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-forcesched.html">ForceScheduler</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-irenderable.html">IRenderable</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-iproperties.html">IProperties</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes/index.html">Release Notes for Buildbot 0.8.9</a></li>
</ul>
<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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<a href="classes.html" title="Classes"
>previous</a> |
<a href="cls-buildsetsummarynotifiermixin.html" title="BuildSetSummaryNotifierMixin"
>next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
>index</a>
<br/>
<a href="../_sources/developer/cls-buildfactory.txt"
rel="nofollow">Show Source</a>
</div>
<div class="right">
<div class="footer">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
