<!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>BuildSteps — Buildbot v0.8.5rc2-29-g80a524b 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.5rc2-29-g80a524b',
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 v0.8.5rc2-29-g80a524b documentation" href="../index.html" />
<link rel="up" title="Classes" href="classes.html" />
<link rel="prev" title="RemoteCommands" href="cls-remotecommands.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>
<h1><a href="../index.html">Buildbot v0.8.5rc2-29-g80a524b documentation</a></h1>
<div class="rel">
<a href="cls-remotecommands.html" title="RemoteCommands"
accesskey="P">previous</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="module-buildbot.process.buildstep">
<span id="buildsteps"></span><h1>BuildSteps<a class="headerlink" href="#module-buildbot.process.buildstep" title="Permalink to this headline">¶</a></h1>
<p>There are a few parent classes that are used as base classes for real
buildsteps. This section describes the base classes. The "leaf" classes are
described in <a class="reference internal" href="../manual/cfg-buildsteps.html"><em>Build Steps</em></a>.</p>
<div class="section" id="buildstep">
<h2>BuildStep<a class="headerlink" href="#buildstep" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="buildbot.process.buildstep.BuildStep">
<em class="property">class </em><tt class="descclassname">buildbot.process.buildstep.</tt><tt class="descname">BuildStep</tt><big>(</big><em>name</em>, <em>locks</em>, <em>haltOnFailure</em>, <em>flunkOnWarnings</em>, <em>flunkOnFailure</em>, <em>warnOnWarnings</em>, <em>warnOnFailure</em>, <em>alwaysRun</em>, <em>progressMetrics</em>, <em>useProgress</em>, <em>doStepIf</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep" title="Permalink to this definition">¶</a></dt>
<dd><p>All constructor arguments must be given as keyword arguments. Each
constructor parameter is copied to the corresponding attribute.</p>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.name">
<tt class="descname">name</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of the step.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.locks">
<tt class="descname">locks</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.locks" title="Permalink to this definition">¶</a></dt>
<dd><p>List of locks for this step; see <a class="reference internal" href="../manual/cfg-interlocks.html#interlocks"><em>Interlocks</em></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.progressMetrics">
<tt class="descname">progressMetrics</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.progressMetrics" title="Permalink to this definition">¶</a></dt>
<dd><p>List of names of metrics that should be used to track the progress of
this build, and build ETA's for users. This is generally set in the</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.useProgress">
<tt class="descname">useProgress</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.useProgress" title="Permalink to this definition">¶</a></dt>
<dd><p>If true (the default), then ETAs will be calculated for this step using
progress metrics. If the step is known to have unpredictable timing
(e.g., an incremental build), then this should be set to false.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.doStepIf">
<tt class="descname">doStepIf</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.doStepIf" title="Permalink to this definition">¶</a></dt>
<dd><p>A callable to determine whether this step should be executed. See
<a class="reference internal" href="../manual/cfg-buildsteps.html#buildstep-common-parameters"><em>Common Parameters</em></a> for details.</p>
</dd></dl>
<p>The following attributes affect the behavior of the containing build:</p>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.haltOnFailure">
<tt class="descname">haltOnFailure</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.haltOnFailure" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the build will halt on a failure of this step, and not execute
subsequent tests (except those with <tt class="docutils literal"><span class="pre">alwaysRun</span></tt>).</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.flunkOnWarnings">
<tt class="descname">flunkOnWarnings</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.flunkOnWarnings" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the build will be marked as a failure if this step ends with
warnings.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.flunkOnFailure">
<tt class="descname">flunkOnFailure</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.flunkOnFailure" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the build will be marked as a failure if this step fails.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.warnOnWarnings">
<tt class="descname">warnOnWarnings</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.warnOnWarnings" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the build will be marked as warnings, or worse, if this step
ends with warnings.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.warnOnFailure">
<tt class="descname">warnOnFailure</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.warnOnFailure" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the build will be marked as warnings, or worse, if this step
fails.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.alwaysRun">
<tt class="descname">alwaysRun</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.alwaysRun" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, the step will run even if a previous step halts the build with
<tt class="docutils literal"><span class="pre">haltOnFailure</span></tt>.</p>
</dd></dl>
<p>A step acts as a factory for more steps. See
<a class="reference internal" href="../manual/customization.html#writing-buildstep-constructors"><em>Writing BuildStep Constructors</em></a> for advice on writing subclass
constructors. The following methods handle this factory behavior.</p>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.addFactoryArguments">
<tt class="descname">addFactoryArguments</tt><big>(</big><em>..</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.addFactoryArguments" title="Permalink to this definition">¶</a></dt>
<dd><p>Add the given keyword arguments to the arguments used to create new
step instances;</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.getStepFactory">
<tt class="descname">getStepFactory</tt><big>(</big><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.getStepFactory" 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"><th class="field-name">Returns:</th><td class="field-body">tuple of (class, keyword arguments)</td>
</tr>
</tbody>
</table>
<p>Get a factory for new instances of this step. The step can be created
by calling the class with the given keyword arguments.</p>
</dd></dl>
<p>A few important pieces of information are not available when a step is
constructed, and are added later. These are set by the following methods;
the order in which these methods are called is not defined.</p>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.setBuild">
<tt class="descname">setBuild</tt><big>(</big><em>build</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.setBuild" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>build</strong> -- the <tt class="xref py py-class docutils literal"><span class="pre">Build</span></tt> instance
controlling this step.</td>
</tr>
</tbody>
</table>
<p>This method is called during setup to set the build instance
controlling this slave. Subclasses can override this to get access to
the build object as soon as it is available. The default
implementation sets the <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.build" title="buildbot.process.buildstep.BuildStep.build"><tt class="xref py py-attr docutils literal"><span class="pre">build</span></tt></a> attribute.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.build">
<tt class="descname">build</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.build" title="Permalink to this definition">¶</a></dt>
<dd><p>The build object controlling this step.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.setBuildSlave">
<tt class="descname">setBuildSlave</tt><big>(</big><em>build</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.setBuildSlave" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>build</strong> -- the <tt class="xref py py-class docutils literal"><span class="pre">BuildSlave</span></tt> instance on
which this step will run.</td>
</tr>
</tbody>
</table>
<p>Similarly, this method is called with the build slave that will run
this step. The default implementation sets the <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.buildslave" title="buildbot.process.buildstep.BuildStep.buildslave"><tt class="xref py py-attr docutils literal"><span class="pre">buildslave</span></tt></a>
attribute.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.buildslave">
<tt class="descname">buildslave</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.buildslave" title="Permalink to this definition">¶</a></dt>
<dd><p>The build slave that will run this step.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.setDefaultWorkdir">
<tt class="descname">setDefaultWorkdir</tt><big>(</big><em>workdir</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.setDefaultWorkdir" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>workdir</strong> -- the default workdir, from the build</td>
</tr>
</tbody>
</table>
<p>This method is called at build startup with the default workdir for the
build. Steps which allow a workdir to be specified, but want to
override it with the build's default workdir, can use this method to
apply the default.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.setStepStatus">
<tt class="descname">setStepStatus</tt><big>(</big><em>status</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.setStepStatus" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>status</strong> (<tt class="xref py py-class docutils literal"><span class="pre">BuildStepStatus</span></tt>) -- step status</td>
</tr>
</tbody>
</table>
<p>This method is called to set the status instance to which the step
should report. The default implementation sets <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.step_status" title="buildbot.process.buildstep.BuildStep.step_status"><tt class="xref py py-attr docutils literal"><span class="pre">step_status</span></tt></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.step_status">
<tt class="descname">step_status</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.step_status" title="Permalink to this definition">¶</a></dt>
<dd><p>The <tt class="xref py py-class docutils literal"><span class="pre">BuildStepStatus</span></tt> object tracking
the status of this step.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.setupProgress">
<tt class="descname">setupProgress</tt><big>(</big><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.setupProgress" title="Permalink to this definition">¶</a></dt>
<dd><p>This method is called during build setup to give the step a chance to
set up progress tracking. It is only called if the build has
<a class="reference internal" href="#buildbot.process.buildstep.BuildStep.useProgress" title="buildbot.process.buildstep.BuildStep.useProgress"><tt class="xref py py-attr docutils literal"><span class="pre">useProgress</span></tt></a> set. There is rarely any reason to override this
method.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.progress">
<tt class="descname">progress</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.progress" title="Permalink to this definition">¶</a></dt>
<dd><p>If the step is tracking progress, this is a
<tt class="xref py py-class docutils literal"><span class="pre">StepProgress</span></tt> instance performing
that task.</p>
</dd></dl>
<p>Exeuction of the step itself is governed by the following methods and attributes.</p>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.startStep">
<tt class="descname">startStep</tt><big>(</big><em>remote</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.startStep" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>remote</strong> -- a remote reference to the slave-side
<tt class="xref py py-class docutils literal"><span class="pre">SlaveBuilder</span></tt> instance</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">Deferred</td>
</tr>
</tbody>
</table>
<p>Begin the step. This is the build's interface to step execution.
Subclasses should override <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.start" title="buildbot.process.buildstep.BuildStep.start"><tt class="xref py py-meth docutils literal"><span class="pre">start</span></tt></a> to implement custom behaviors.</p>
<p>The method returns a Deferred that fires when the step finishes. It
fires with a tuple of <tt class="docutils literal"><span class="pre">(result,</span> <span class="pre">[extra</span> <span class="pre">text])</span></tt>, where <tt class="docutils literal"><span class="pre">result</span></tt> is
one of the constants from <tt class="xref py py-mod docutils literal"><span class="pre">buildbot.status.builder</span></tt>. The extra
text is a list of short strings which should be appended to the Build's
text results. For example, a test step may add <tt class="docutils literal"><span class="pre">17</span> <span class="pre">failures</span></tt> to the
Build's status by this mechanism.</p>
<p>The deferred will errback if the step encounters an exception,
including an exception on the slave side (or if the slave goes away
altogether). Normal build/test failures will <em>not</em> cause an errback.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.start">
<tt class="descname">start</tt><big>(</big><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.start" 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"><th class="field-name">Returns:</th><td class="field-body"><tt class="xref docutils literal"><span class="pre">None</span></tt> or <a class="reference internal" href="results.html#buildbot.status.results.SKIPPED" title="buildbot.status.results.SKIPPED"><tt class="xref py py-data docutils literal"><span class="pre">SKIPPED</span></tt></a></td>
</tr>
</tbody>
</table>
<p>Begin the step. Subclasses should override this method to do local
processing, fire off remote commands, etc. The parent method raises
<tt class="xref py py-exc docutils literal"><span class="pre">NotImplementedError</span></tt>.</p>
<p>Note that this method does <em>not</em> return a Deferred. When the step is
done, it should call <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.finished" title="buildbot.process.buildstep.BuildStep.finished"><tt class="xref py py-meth docutils literal"><span class="pre">finished</span></tt></a>, with a result -- a constant from
<a class="reference internal" href="results.html#module-buildbot.status.results" title="buildbot.status.results"><tt class="xref py py-mod docutils literal"><span class="pre">buildbot.status.results</span></tt></a>. The result will be handed off to
the <tt class="xref py py-class docutils literal"><span class="pre">Build</span></tt>.</p>
<p>If the step encounters an exception, it should call <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.failed" title="buildbot.process.buildstep.BuildStep.failed"><tt class="xref py py-meth docutils literal"><span class="pre">failed</span></tt></a> with
a Failure object. This method automatically fails the whole build with
an exception. A common idiom is to add <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.failed" title="buildbot.process.buildstep.BuildStep.failed"><tt class="xref py py-meth docutils literal"><span class="pre">failed</span></tt></a> as an errback on
a Deferred:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">cmd</span> <span class="o">=</span> <span class="n">LoggedRemoteCommand</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
<span class="n">d</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">runCommand</span><span class="p">(</span><span class="n">cmd</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">suceed</span><span class="p">(</span><span class="n">_</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">finished</span><span class="p">(</span><span class="n">results</span><span class="o">.</span><span class="n">SUCCESS</span><span class="p">)</span>
<span class="n">d</span><span class="o">.</span><span class="n">addCallback</span><span class="p">(</span><span class="n">succeed</span><span class="p">)</span>
<span class="n">d</span><span class="o">.</span><span class="n">addErrback</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">failed</span><span class="p">)</span>
</pre></div>
</div>
<p>If the step decides it does not need to be run, <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.start" title="buildbot.process.buildstep.BuildStep.start"><tt class="xref py py-meth docutils literal"><span class="pre">start</span></tt></a> can
return the constant <a class="reference internal" href="results.html#buildbot.status.results.SKIPPED" title="buildbot.status.results.SKIPPED"><tt class="xref py py-data docutils literal"><span class="pre">SKIPPED</span></tt></a>. In this
case, it is not necessary to call <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.finished" title="buildbot.process.buildstep.BuildStep.finished"><tt class="xref py py-meth docutils literal"><span class="pre">finished</span></tt></a> directly.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.finished">
<tt class="descname">finished</tt><big>(</big><em>results</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.finished" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>results</strong> -- a constant from <a class="reference internal" href="results.html#module-buildbot.status.results" title="buildbot.status.results"><tt class="xref py py-mod docutils literal"><span class="pre">results</span></tt></a></td>
</tr>
</tbody>
</table>
<p>A call to this method indicates that the step is finished and the build
should analyze the results and perhaps proceed to the next step. The
step should not perform any additional processing after calling this
method.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.failed">
<tt class="descname">failed</tt><big>(</big><em>failure</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.failed" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>failure</strong> -- a <tt class="xref py py-class docutils literal"><span class="pre">Failure</span></tt> instance</td>
</tr>
</tbody>
</table>
<p>Similar to <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.finished" title="buildbot.process.buildstep.BuildStep.finished"><tt class="xref py py-meth docutils literal"><span class="pre">finished</span></tt></a>, this method indicates that the step is
finished, but handles exceptions with appropriate logging and
diagnostics.</p>
<p>This method handles <a class="reference internal" href="#buildbot.process.buildstep.BuildStepFailed" title="buildbot.process.buildstep.BuildStepFailed"><tt class="xref py py-exc docutils literal"><span class="pre">BuildStepFailed</span></tt></a> specially, by calling
<tt class="docutils literal"><span class="pre">finished(FAILURE)</span></tt>. This provides subclasses with a shortcut to
stop execution of a step by raising this failure in a context where
<a class="reference internal" href="#buildbot.process.buildstep.BuildStep.failed" title="buildbot.process.buildstep.BuildStep.failed"><tt class="xref py py-meth docutils literal"><span class="pre">failed</span></tt></a> will catch it.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.interrupt">
<tt class="descname">interrupt</tt><big>(</big><em>reason</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.interrupt" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>reason</strong> (string or <tt class="xref py py-class docutils literal"><span class="pre">Failure</span></tt>) -- why the build was interrupted</td>
</tr>
</tbody>
</table>
<p>This method is used from various control interfaces to stop a running
step. The step should be brought to a halt as quickly as possible, by
cancelling a remote command, killing a local process, etc. The step
must still finish with either <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.finished" title="buildbot.process.buildstep.BuildStep.finished"><tt class="xref py py-meth docutils literal"><span class="pre">finished</span></tt></a> or <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.failed" title="buildbot.process.buildstep.BuildStep.failed"><tt class="xref py py-meth docutils literal"><span class="pre">failed</span></tt></a>.</p>
<p>The <tt class="docutils literal"><span class="pre">reason</span></tt> parameter can be a string or, when a slave is lost
during step processing, a <tt class="xref py py-exc docutils literal"><span class="pre">ConnectionLost</span></tt>
failure.</p>
<p>The parent method handles any pending lock operations, and should be
called by implementations in subclasses.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.process.buildstep.BuildStep.stopped">
<tt class="descname">stopped</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.stopped" title="Permalink to this definition">¶</a></dt>
<dd><p>If false, then the step is running. If true, the step is not running,
or has been interrupted.</p>
</dd></dl>
<p>This method provides a convenient way to summarize the status of the step
for status displays:</p>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.describe">
<tt class="descname">describe</tt><big>(</big><em>done=False</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.describe" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>done</strong> -- If true, the step is finished.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">list of strings</td>
</tr>
</tbody>
</table>
<p>Describe the step succinctly. The return value should be a sequence of
short strings suitable for display in a horizontally constrained space.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Be careful not to assume that the step has been started in this
method. In relatively rare circumstances, steps are described
before they have started. Ideally, unit tests should be used to
ensure that this method is resilient.</p>
</div>
</dd></dl>
<p>Build steps support progress metrics - values that increase roughly
linearly during the execution of the step, and can thus be used to
calculate an expected completion time for a running step. A metric may be
a count of lines logged, tests executed, or files compiled. The build
mechanics will take care of translating this progress information into an
ETA for the user.</p>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.setProgress">
<tt class="descname">setProgress</tt><big>(</big><em>metric</em>, <em>value</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.setProgress" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>metric</strong> (<em>string</em>) -- the metric to update</li>
<li><strong>value</strong> (<em>integer</em>) -- the new value for the metric</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Update a progress metric. This should be called by subclasses that can
provide useful progress-tracking information.</p>
<p>The specified metric name must be included in <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.progressMetrics" title="buildbot.process.buildstep.BuildStep.progressMetrics"><tt class="xref py py-attr docutils literal"><span class="pre">progressMetrics</span></tt></a>.</p>
</dd></dl>
<p>The following methods are provided as utilities to subclasses. These
methods should only be invoked after the step is started.</p>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.slaveVersion">
<tt class="descname">slaveVersion</tt><big>(</big><em>command</em>, <em>oldVersion=None</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.slaveVersion" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>command</strong> (<em>string</em>) -- command to examine</li>
<li><strong>oldVersion</strong> -- return value if the slave does not specify a version</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">string</p>
</td>
</tr>
</tbody>
</table>
<p>Fetch the version of the named command, as specified on the slave. In
practice, all commands on a slave have the same version, but passing
<tt class="docutils literal"><span class="pre">command</span></tt> is still useful to ensure that the command is implemented
on the slave. If the command is not implemented on the slave,
<a class="reference internal" href="#buildbot.process.buildstep.BuildStep.slaveVersion" title="buildbot.process.buildstep.BuildStep.slaveVersion"><tt class="xref py py-meth docutils literal"><span class="pre">slaveVersion</span></tt></a> will return <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p>
<p>Versions take the form <tt class="docutils literal"><span class="pre">x.y</span></tt> where <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt> are integers, and
are compared as expected for version numbers.</p>
<p>Buildbot versions older than 0.5.0 did not support version queries; in
this case, <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.slaveVersion" title="buildbot.process.buildstep.BuildStep.slaveVersion"><tt class="xref py py-meth docutils literal"><span class="pre">slaveVersion</span></tt></a> will return <tt class="docutils literal"><span class="pre">oldVersion</span></tt>. Since such
ancient versions of Buildbot are no longer in use, this functionality
is largely vestigial.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.slaveVersionIsOlderThan">
<tt class="descname">slaveVersionIsOlderThan</tt><big>(</big><em>command</em>, <em>minversion</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.slaveVersionIsOlderThan" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>command</strong> (<em>string</em>) -- command to examine</li>
<li><strong>minversion</strong> -- minimum version</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">boolean</p>
</td>
</tr>
</tbody>
</table>
<p>This method returns true if <tt class="docutils literal"><span class="pre">command</span></tt> is not implemented on the
slave, or if it is older than <tt class="docutils literal"><span class="pre">minversion</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.getSlaveName">
<tt class="descname">getSlaveName</tt><big>(</big><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.getSlaveName" 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"><th class="field-name">Returns:</th><td class="field-body">string</td>
</tr>
</tbody>
</table>
<p>Get the name of the buildslave assigned to this step.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.runCommand">
<tt class="descname">runCommand</tt><big>(</big><em>command</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.runCommand" 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"><th class="field-name">Returns:</th><td class="field-body">Deferred</td>
</tr>
</tbody>
</table>
<p>This method connects the given command to the step's buildslave and
runs it, returning the Deferred from
<a class="reference internal" href="cls-remotecommands.html#buildbot.process.buildstep.RemoteCommand.run" title="buildbot.process.buildstep.RemoteCommand.run"><tt class="xref py py-meth docutils literal"><span class="pre">run</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.addURL">
<tt class="descname">addURL</tt><big>(</big><em>name</em>, <em>url</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.addURL" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>name</strong> -- URL name</li>
<li><strong>url</strong> -- the URL</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Add a link to the given <tt class="docutils literal"><span class="pre">url</span></tt>, with the given <tt class="docutils literal"><span class="pre">name</span></tt> to displays of
this step. This allows a step to provide links to data that is not
available in the log files.</p>
</dd></dl>
<p>The <a class="reference internal" href="#buildbot.process.buildstep.BuildStep" title="buildbot.process.buildstep.BuildStep"><tt class="xref py py-class docutils literal"><span class="pre">BuildStep</span></tt></a> class provides minimal support for log handling,
that is extended by the <a class="reference internal" href="#buildbot.process.buildstep.LoggingBuildStep" title="buildbot.process.buildstep.LoggingBuildStep"><tt class="xref py py-class docutils literal"><span class="pre">LoggingBuildStep</span></tt></a> class. The following
methods provide some useful behaviors. These methods can be called while
the step is running, but not before.</p>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.addLog">
<tt class="descname">addLog</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.addLog" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>name</strong> -- log name</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><a class="reference internal" href="formats.html#buildbot.status.logfile.LogFile" title="buildbot.status.logfile.LogFile"><tt class="xref py py-class docutils literal"><span class="pre">LogFile</span></tt></a> instance</td>
</tr>
</tbody>
</table>
<p>Add a new logfile with the given name to the step, and return the log
file instance.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.getLog">
<tt class="descname">getLog</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.getLog" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>name</strong> -- log name</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><a class="reference internal" href="formats.html#buildbot.status.logfile.LogFile" title="buildbot.status.logfile.LogFile"><tt class="xref py py-class docutils literal"><span class="pre">LogFile</span></tt></a> instance</td>
</tr>
<tr class="field"><th class="field-name">Raises :</th><td class="field-body"><tt class="xref py py-exc docutils literal"><span class="pre">KeyError</span></tt> if the log is not found</td>
</tr>
</tbody>
</table>
<p>Get an existing logfile by name.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.addCompleteLog">
<tt class="descname">addCompleteLog</tt><big>(</big><em>name</em>, <em>text</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.addCompleteLog" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>name</strong> -- log name</li>
<li><strong>text</strong> -- content of the logfile</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>This method adds a new log and sets <tt class="docutils literal"><span class="pre">text</span></tt> as its content. This is
often useful to add a short logfile describing activities performed on
the master. The logfile is immediately closed, and no further data can
be added.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.addHTMLLog">
<tt class="descname">addHTMLLog</tt><big>(</big><em>name</em>, <em>html</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.addHTMLLog" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>name</strong> -- log name</li>
<li><strong>html</strong> -- content of the logfile</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Similar to <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.addCompleteLog" title="buildbot.process.buildstep.BuildStep.addCompleteLog"><tt class="xref py py-meth docutils literal"><span class="pre">addCompleteLog</span></tt></a>, this adds a logfile containing
pre-formatted HTML, allowing more expressiveness than the text format
supported by <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.addCompleteLog" title="buildbot.process.buildstep.BuildStep.addCompleteLog"><tt class="xref py py-meth docutils literal"><span class="pre">addCompleteLog</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.BuildStep.addLogObserver">
<tt class="descname">addLogObserver</tt><big>(</big><em>logname</em>, <em>observer</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.BuildStep.addLogObserver" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>logname</strong> -- log name</li>
<li><strong>observer</strong> -- log observer instance</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Add a log observer for the named log. The named log need not have been
added already: the observer will be connected when the log is added.</p>
<p>See <a class="reference internal" href="../manual/customization.html#adding-logobservers"><em>Adding LogObservers</em></a> for more information on log observers.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="loggingbuildstep">
<h2>LoggingBuildStep<a class="headerlink" href="#loggingbuildstep" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="buildbot.process.buildstep.LoggingBuildStep">
<em class="property">class </em><tt class="descclassname">buildbot.process.buildstep.</tt><tt class="descname">LoggingBuildStep</tt><big>(</big><em>logfiles</em>, <em>lazylogfiles</em>, <em>log_eval_func</em>, <em>name</em>, <em>locks</em>, <em>haltOnFailure</em>, <em>flunkOnWarnings</em>, <em>flunkOnFailure</em>, <em>warnOnWarnings</em>, <em>warnOnFailure</em>, <em>alwaysRun</em>, <em>progressMetrics</em>, <em>useProgress</em>, <em>doStepIf</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.LoggingBuildStep" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>logfiles</strong> -- see <a class="reference internal" href="../manual/cfg-buildsteps.html#step-ShellCommand" title="ShellCommand"><tt class="xref bb bb-step docutils literal"><span class="pre">ShellCommand</span></tt></a></li>
<li><strong>lazylogfiles</strong> -- see <a class="reference internal" href="../manual/cfg-buildsteps.html#step-ShellCommand" title="ShellCommand"><tt class="xref bb bb-step docutils literal"><span class="pre">ShellCommand</span></tt></a></li>
<li><strong>log_eval_func</strong> -- see <a class="reference internal" href="../manual/cfg-buildsteps.html#step-ShellCommand" title="ShellCommand"><tt class="xref bb bb-step docutils literal"><span class="pre">ShellCommand</span></tt></a></li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>The remaining arguments are passed to the <a class="reference internal" href="#buildbot.process.buildstep.BuildStep" title="buildbot.process.buildstep.BuildStep"><tt class="xref py py-class docutils literal"><span class="pre">BuildStep</span></tt></a> constructor.</p>
<p>This subclass of <a class="reference internal" href="#buildbot.process.buildstep.BuildStep" title="buildbot.process.buildstep.BuildStep"><tt class="xref py py-class docutils literal"><span class="pre">BuildStep</span></tt></a> is designed to help its subclasses run
remote commands that produce standard I/O logfiles. It:</p>
<ul class="simple">
<li>tracks progress using the length of the stdout logfile</li>
<li>provides hooks for summarizing and evaluating the command's result</li>
<li>supports lazy logfiles</li>
<li>handles the mechanics of starting, interrupting, and finishing remote
commands</li>
<li>detects lost slaves and finishes with a status of
<a class="reference internal" href="results.html#buildbot.status.results.RETRY" title="buildbot.status.results.RETRY"><tt class="xref py py-data docutils literal"><span class="pre">RETRY</span></tt></a></li>
</ul>
<dl class="attribute">
<dt id="buildbot.process.buildstep.LoggingBuildStep.logfiles">
<tt class="descname">logfiles</tt><a class="headerlink" href="#buildbot.process.buildstep.LoggingBuildStep.logfiles" title="Permalink to this definition">¶</a></dt>
<dd><p>The logfiles to track, as described for <a class="reference internal" href="../manual/cfg-buildsteps.html#step-ShellCommand" title="ShellCommand"><tt class="xref bb bb-step docutils literal"><span class="pre">ShellCommand</span></tt></a>. The
contents of the class-level <tt class="docutils literal"><span class="pre">logfiles</span></tt> attribute are combined with
those passed to the constructor, so subclasses may add log files with a
class attribute:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyStep</span><span class="p">(</span><span class="n">LoggingBuildStep</span><span class="p">):</span>
<span class="n">logfiles</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">debug</span><span class="o">=</span><span class="s">'debug.log'</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that lazy logfiles cannot be specified using this method; they
must be provided as constructor arguments.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.LoggingBuildStep.startCommand">
<tt class="descname">startCommand</tt><big>(</big><em>command</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.LoggingBuildStep.startCommand" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>command</strong> -- the <a class="reference internal" href="cls-remotecommands.html#buildbot.process.buildstep.RemoteCommand" title="buildbot.process.buildstep.RemoteCommand"><tt class="xref py py-class docutils literal"><span class="pre">RemoteCommand</span></tt></a>
instance to start</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<blockquote>
<div>This method permits an optional <tt class="docutils literal"><span class="pre">errorMessages</span></tt> parameter,
allowing errors detected early in the command process to be logged.
It will be removed, and its use is deprecated.</div></blockquote>
<p>Handle all of the mechanics of running the given command. This sets
up all required logfiles, keeps status text up to date, and calls the
utility hooks described below. When the command is finished, the step
is finished as well, making this class is unsuitable for steps that
run more than one command in sequence.</p>
<p>Subclasses should override
<a class="reference internal" href="#buildbot.process.buildstep.BuildStep.start" title="buildbot.process.buildstep.BuildStep.start"><tt class="xref py py-meth docutils literal"><span class="pre">start</span></tt></a> and, after setting
up an appropriate command, call this method.</p>
<div class="last highlight-python"><pre>def start(self):
cmd = RemoteShellCommand(..)
self.startCommand(cmd, warnings)</pre>
</div>
</div>
</dd></dl>
<p>To refine the status output, override one or more of the following methods.
The <a class="reference internal" href="#buildbot.process.buildstep.LoggingBuildStep" title="buildbot.process.buildstep.LoggingBuildStep"><tt class="xref py py-class docutils literal"><span class="pre">LoggingBuildStep</span></tt></a> implementations are stubs, so there is no
need to call the parent method.</p>
<dl class="method">
<dt id="buildbot.process.buildstep.LoggingBuildStep.commandComplete">
<tt class="descname">commandComplete</tt><big>(</big><em>command</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.LoggingBuildStep.commandComplete" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>command</strong> -- the just-completed remote command</td>
</tr>
</tbody>
</table>
<p>This is a general-purpose hook method for subclasses. It will be called
after the remote command has finished, but before any of the other hook
functions are called.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.LoggingBuildStep.createSummary">
<tt class="descname">createSummary</tt><big>(</big><em>stdio</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.LoggingBuildStep.createSummary" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>stdio</strong> -- stdio <a class="reference internal" href="formats.html#buildbot.status.logfile.LogFile" title="buildbot.status.logfile.LogFile"><tt class="xref py py-class docutils literal"><span class="pre">LogFile</span></tt></a></td>
</tr>
</tbody>
</table>
<p>This hook is designed to perform any summarization of the step, based
either on the contents of the stdio logfile, or on instance attributes
set earlier in the step processing. Implementations of this method
often call e.g., <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.addURL" title="buildbot.process.buildstep.BuildStep.addURL"><tt class="xref py py-meth docutils literal"><span class="pre">addURL</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.LoggingBuildStep.evaluateCommand">
<tt class="descname">evaluateCommand</tt><big>(</big><em>command</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.LoggingBuildStep.evaluateCommand" 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"><th class="field-name">Parameters:</th><td class="field-body"><strong>command</strong> -- the just-completed remote command</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">step result from <a class="reference internal" href="results.html#module-buildbot.status.results" title="buildbot.status.results"><tt class="xref py py-mod docutils literal"><span class="pre">buildbot.status.results</span></tt></a></td>
</tr>
</tbody>
</table>
<p>This hook should decide what result the step should have. The default
implementation invokes <tt class="docutils literal"><span class="pre">log_eval_func</span></tt> if it exists, and looks at
<tt class="xref py py-attr docutils literal"><span class="pre">rc</span></tt> to distinguish
<a class="reference internal" href="results.html#buildbot.status.results.SUCCESS" title="buildbot.status.results.SUCCESS"><tt class="xref py py-data docutils literal"><span class="pre">SUCCESS</span></tt></a> from
<a class="reference internal" href="results.html#buildbot.status.results.FAILURE" title="buildbot.status.results.FAILURE"><tt class="xref py py-data docutils literal"><span class="pre">FAILURE</span></tt></a>.</p>
</dd></dl>
<p>The remaining methods provide an embarassment of ways to set the summary of
the step that appears in the various status interfaces. The easiest way to
affect this output is to override <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.describe" title="buildbot.process.buildstep.BuildStep.describe"><tt class="xref py py-meth docutils literal"><span class="pre">describe</span></tt></a>. If that is
not flexible enough, override <a class="reference internal" href="#buildbot.process.buildstep.LoggingBuildStep.getText" title="buildbot.process.buildstep.LoggingBuildStep.getText"><tt class="xref py py-meth docutils literal"><span class="pre">getText</span></tt></a> and/or <a class="reference internal" href="#buildbot.process.buildstep.LoggingBuildStep.getText2" title="buildbot.process.buildstep.LoggingBuildStep.getText2"><tt class="xref py py-meth docutils literal"><span class="pre">getText2</span></tt></a>.</p>
<dl class="method">
<dt id="buildbot.process.buildstep.LoggingBuildStep.getText">
<tt class="descname">getText</tt><big>(</big><em>command</em>, <em>results</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.LoggingBuildStep.getText" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>command</strong> -- the just-completed remote command</li>
<li><strong>results</strong> -- step result from <a class="reference internal" href="#buildbot.process.buildstep.LoggingBuildStep.evaluateCommand" title="buildbot.process.buildstep.LoggingBuildStep.evaluateCommand"><tt class="xref py py-meth docutils literal"><span class="pre">evaluateCommand</span></tt></a></li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a list of short strings</p>
</td>
</tr>
</tbody>
</table>
<p>This method is the primary means of describing the step. The default
implementation calls <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.describe" title="buildbot.process.buildstep.BuildStep.describe"><tt class="xref py py-meth docutils literal"><span class="pre">describe</span></tt></a>, which is usally the
easiest method to override, and then appends a string describing the
step status if it was not successful.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.process.buildstep.LoggingBuildStep.getText2">
<tt class="descname">getText2</tt><big>(</big><em>command</em>, <em>results</em><big>)</big><a class="headerlink" href="#buildbot.process.buildstep.LoggingBuildStep.getText2" 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"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>command</strong> -- the just-completed remote command</li>
<li><strong>results</strong> -- step result from <a class="reference internal" href="#buildbot.process.buildstep.LoggingBuildStep.evaluateCommand" title="buildbot.process.buildstep.LoggingBuildStep.evaluateCommand"><tt class="xref py py-meth docutils literal"><span class="pre">evaluateCommand</span></tt></a></li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a list of short strings</p>
</td>
</tr>
</tbody>
</table>
<p>Like <a class="reference internal" href="#buildbot.process.buildstep.LoggingBuildStep.getText" title="buildbot.process.buildstep.LoggingBuildStep.getText"><tt class="xref py py-meth docutils literal"><span class="pre">getText</span></tt></a>, this method summarizes the step's result, but it
is only called when that result affects the build, either by making it
halt, flunk, or end with warnings.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="exceptions">
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2>
<dl class="exception">
<dt id="buildbot.process.buildstep.BuildStepFailed">
<em class="property">exception </em><tt class="descclassname">buildbot.process.buildstep.</tt><tt class="descname">BuildStepFailed</tt><a class="headerlink" href="#buildbot.process.buildstep.BuildStepFailed" title="Permalink to this definition">¶</a></dt>
<dd><p>This exception indicates that the buildstep has failed. It is useful as a
way to skip all subsequent processing when a step goes wrong. It is
handled by <a class="reference internal" href="#buildbot.process.buildstep.BuildStep.failed" title="buildbot.process.buildstep.BuildStep.failed"><tt class="xref py py-meth docutils literal"><span class="pre">BuildStep.failed</span></tt></a>.</p>
</dd></dl>
</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="style.html">Buildbot Coding Style</a></li>
<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="config.html">Buildbot 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">The Buildbot 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"><a class="reference internal" href="cls-buildfactory.html">BuildFactory</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-remotecommands.html">RemoteCommands</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="">BuildSteps</a><ul class="simple">
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<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="cls-remotecommands.html" title="RemoteCommands"
>previous</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-buildsteps.txt"
rel="nofollow">Show Source</a>
</div>
<div class="right">
<div class="footer">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
