<!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.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="Classes" href="classes.html" />
<link rel="next" title="BuildSetSummaryNotifierMixin" href="cls-buildsetsummarynotifiermixin.html" />
<link rel="prev" title="Classes" href="classes.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="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" role="main">
<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 <code class="xref py py-class docutils literal"><span class="pre">BuildFactory</span></code>, provided in the
<code class="xref py py-mod docutils literal"><span class="pre">buildbot.process.factory</span></code> module, contains an internal list of
<cite>BuildStep specifications</cite>: a list of <code class="docutils literal"><span class="pre">(step_class,</span> <span class="pre">kwargs)</span></code>
tuples for each. These specification tuples are constructed when the
config file is read, by asking the instances passed to <code class="xref py py-meth docutils literal"><span class="pre">addStep</span></code>
for their subclass and arguments.</p>
<p>To support config files from buildbot-0.7.5 and earlier,
<code class="xref py py-meth docutils literal"><span class="pre">addStep</span></code> also accepts the <code class="docutils literal"><span class="pre">f.addStep(shell.Compile,</span>
<span class="pre">command=["make","build"])</span></code> form, although its use is discouraged
because then the <code class="docutils literal"><span class="pre">Compile</span></code> 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 <code class="xref py py-class docutils literal"><span class="pre">Build</span></code>, the <code class="xref py py-class docutils literal"><span class="pre">BuildFactory</span></code> puts a copy of
the list of step specifications into the new <code class="xref py py-class docutils literal"><span class="pre">Build</span></code> object. When the
<code class="xref py py-class docutils literal"><span class="pre">Build</span></code> is actually started, these step specifications are used to
create the actual set of <code class="xref py py-class docutils literal"><span class="pre">BuildStep</span></code>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 <code class="xref py py-attr docutils literal"><span class="pre">haltOnFailure</span></code> attribute is <code class="docutils literal"><span class="pre">True</span></code>, then a failure
in the step (i.e. if it completes with a result of <code class="docutils literal"><span class="pre">FAILURE</span></code>) will cause
the whole build to be terminated immediately: no further steps will be
executed, with the exception of steps with <code class="xref py py-attr docutils literal"><span class="pre">alwaysRun</span></code> set to
<code class="docutils literal"><span class="pre">True</span></code>. <code class="xref py py-attr docutils literal"><span class="pre">haltOnFailure</span></code> 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 <code class="xref py py-attr docutils literal"><span class="pre">alwaysRun</span></code> attribute is <code class="docutils literal"><span class="pre">True</span></code>, 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 <code class="xref py py-attr docutils literal"><span class="pre">flunkOnFailure</span></code> or <code class="xref py py-attr docutils literal"><span class="pre">flunkOnWarnings</span></code> flag is set,
then a result of <code class="docutils literal"><span class="pre">FAILURE</span></code> or <code class="docutils literal"><span class="pre">WARNINGS</span></code> will mark the build as a whole as
<code class="docutils literal"><span class="pre">FAILED</span></code>. 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 <code class="xref py py-attr docutils literal"><span class="pre">warnOnFailure</span></code> or <code class="xref py py-attr docutils literal"><span class="pre">warnOnWarnings</span></code> flag
is set, then a result of <code class="docutils literal"><span class="pre">FAILURE</span></code> or <code class="docutils literal"><span class="pre">WARNINGS</span></code> will mark the build as
having <code class="docutils literal"><span class="pre">WARNINGS</span></code>, 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 <code class="docutils literal"><span class="pre">WARNINGS</span></code> result but not be serious
enough to warrant marking the whole build with a <code class="docutils literal"><span class="pre">FAILURE</span></code>.</li>
</ul>
</div></blockquote>
<p>In addition, each <code class="xref py py-class docutils literal"><span class="pre">Step</span></code> 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 <code class="xref py py-class docutils literal"><span class="pre">BuildStep</span></code>s like <code class="xref py py-class docutils literal"><span class="pre">CVS</span></code> and <code class="xref py py-class docutils literal"><span class="pre">Compile</span></code> have
reasonably appropriate flags set on them already. For example, without
a source tree there is no point in continuing the build, so the
<code class="xref py py-class docutils literal"><span class="pre">CVS</span></code> class has the <code class="xref py py-attr docutils literal"><span class="pre">haltOnFailure</span></code> flag set to <code class="docutils literal"><span class="pre">True</span></code>. Look
in <code class="file docutils literal"><span class="pre">buildbot/steps/*.py</span></code> to see how the other <code class="xref py py-class docutils literal"><span class="pre">Step</span></code>s are
marked.</p>
<p>Each <code class="xref py py-class docutils literal"><span class="pre">Step</span></code> is created with an additional <code class="docutils literal"><span class="pre">workdir</span></code> 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 <code class="file docutils literal"><span class="pre">build</span></code>. 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"><a class="reference internal" href="plugins-publish.html">How to package Buildbot plugins</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.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="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>
</div>
<div role="note" aria-label="source link">
<br/>
<a href="../_sources/developer/cls-buildfactory.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>
