Package buildbot :: Package process :: Module buildstep :: Class BuildStep
[frames] | no frames]

Class BuildStep

source code

Known Subclasses:

I represent a single step of the build process. This step may involve zero or more commands to be run in the build slave, as well as arbitrary processing on the master side. Regardless of how many slave commands are run, the BuildStep will result in a single status value.

The step is started by calling startStep(), which returns a Deferred that fires when the step finishes. See startStep for a description of the results provided by that Deferred.

__init__ and start are good methods to override. Don't forget to upcall BuildStep.__init__ or bad things will happen.

To launch a RemoteCommand, pass it to .runCommand and wait on the Deferred it returns.

Each BuildStep generates status as it runs. This status data is fed to the buildbot.status.builder.BuildStepStatus listener that sits in self.step_status. It can also feed progress data (like how much text is output by a shell command) to the buildbot.status.progress.StepProgress object that lives in self.progress, by calling self.setProgress(metric, value) as it runs.

Instance Methods
 
__init__(self, **kwargs) source code
 
describe(self, done=False) source code
 
setBuild(self, build) source code
 
setBuildSlave(self, buildslave) source code
 
setDefaultWorkdir(self, workdir) source code
 
addFactoryArguments(self, **kwargs) source code
 
getStepFactory(self) source code
 
setStepStatus(self, step_status) source code
 
setupProgress(self) source code
 
setProgress(self, metric, value)
BuildSteps can call self.setProgress() to announce progress along some metric.
source code
 
getProperty(self, propname) source code
 
setProperty(self, propname, value, source='Step') source code
 
startStep(self, remote)
Begin the step.
source code
 
acquireLocks(self, res=None) source code
 
start(self)
Begin the step.
source code
 
interrupt(self, reason)
Halt the command, either because the user has decided to cancel the build ('reason' is a string), or because the slave has disconnected ('reason' is a ConnectionLost Failure).
source code
 
releaseLocks(self) source code
 
finished(self, results) source code
 
failed(self, why) source code
 
slaveVersion(self, command, oldversion=None)
Return the version number of the given slave command.
source code
 
slaveVersionIsOlderThan(self, command, minversion) source code
 
getSlaveName(self) source code
 
addLog(self, name) source code
 
getLog(self, name) source code
 
addCompleteLog(self, name, text) source code
 
addHTMLLog(self, name, html) source code
 
addLogObserver(self, logname, observer) source code
 
addURL(self, name, url)
Add a BuildStep URL to this step.
source code
 
runCommand(self, c) source code
Class Variables
  haltOnFailure = False
  flunkOnWarnings = False
  flunkOnFailure = False
  warnOnWarnings = False
  warnOnFailure = False
  alwaysRun = False
  parms = ['name', 'locks', 'haltOnFailure', 'flunkOnWarnings', ...
  name = 'generic'
  locks = []
  progressMetrics = ()
  useProgress = True
  doStepIf = True
Instance Variables
buildbot.process.base.Build build = None
the parent Build which is executing this step
buildbot.status.builder.BuildStepStatus step_status = None
collects output status
buildbot.status.progress.StepProgress progress = None
tracks ETA for the step
Method Details

startStep(self, remote)

source code 

Begin the step. This returns a Deferred that will fire when the step finishes.

This deferred fires with a tuple of (result, [extra text]), although older steps used to return just the 'result' value, so the receiving base.Build needs to be prepared to handle that too. result is one of the SUCCESS/WARNINGS/FAILURE/SKIPPED constants from buildbot.status.builder, and the extra text is a list of short strings which should be appended to the Build's text results. This text allows a test-case step which fails to append 17 tests to the Build's status, in addition to marking the build as failing.

The deferred will errback if the step encounters an exception, including an exception on the slave side (or if the slave goes away altogether). Failures in shell commands (rc!=0) will not cause an errback, in general the BuildStep will evaluate the results and decide whether to treat it as a WARNING or FAILURE.

Parameters:

start(self)

source code 

Begin the step. Override this method and add code to do local processing, fire off remote commands, etc.

To spawn a command in the buildslave, create a RemoteCommand instance and run it with self.runCommand:

 c = RemoteCommandFoo(args)
 d = self.runCommand(c)
 d.addCallback(self.fooDone).addErrback(self.failed)

As the step runs, it should send status information to the BuildStepStatus:

 self.step_status.setText(['compile', 'failed'])
 self.step_status.setText2(['4', 'warnings'])

To have some code parse stdio (or other log stream) in realtime, add a LogObserver subclass. This observer can use self.step.setProgress() to provide better progress notification to the step.:

 self.addLogObserver('stdio', MyLogObserver())

To add a LogFile, use self.addLog. Make sure it gets closed when it finishes. When giving a Logfile to a RemoteShellCommand, just ask it to close the log when the command completes:

 log = self.addLog('output')
 cmd = RemoteShellCommand(args)
 cmd.useLog(log, closeWhenFinished=True)

You can also create complete Logfiles with generated text in a single step:

 self.addCompleteLog('warnings', text)

When the step is done, it should call self.finished(result). 'result' will be provided to the buildbot.process.base.Build, and should be one of the constants defined above: SUCCESS, WARNINGS, FAILURE, or SKIPPED.

If the step encounters an exception, it should call self.failed(why). 'why' should be a Failure object. This automatically fails the whole build with an exception. It is a good idea to add self.failed as an errback to any Deferreds you might obtain.

If the step decides it does not need to be run, start() can return the constant SKIPPED. This fires the callback immediately: it is not necessary to call .finished yourself. This can also indicate to the status-reporting mechanism that this step should not be displayed.

A step can be configured to only run under certain conditions. To do this, set the step's doStepIf to a boolean value, or to a function that returns a boolean value. If the value or function result is False, then the step will return SKIPPED without doing anything, otherwise the step will be executed normally. If you set doStepIf to a function, that function should accept one parameter, which will be the Step object itself.

interrupt(self, reason)

source code 

Halt the command, either because the user has decided to cancel the build ('reason' is a string), or because the slave has disconnected ('reason' is a ConnectionLost Failure). Any further local processing should be skipped, and the Step completed with an error status. The results text should say something useful like ['step', 'interrupted'] or ['remote', 'lost']

slaveVersion(self, command, oldversion=None)

source code 

Return the version number of the given slave command. For the commands defined in buildbot.slave.commands, this is the value of 'cvs_ver' at the top of that file. Non-existent commands will return a value of None. Buildslaves running buildbot-0.5.0 or earlier did not respond to the version query: commands on those slaves will return a value of OLDVERSION, so you can distinguish between old buildslaves and missing commands.

If you know that <=0.5.0 buildslaves have the command you want (CVS and SVN existed back then, but none of the other VC systems), then it makes sense to call this with oldversion='old'. If the command you want is newer than that, just leave oldversion= unspecified, and the command will return None for a buildslave that does not implement the command.

addURL(self, name, url)

source code 

Add a BuildStep URL to this step.

An HREF to this URL will be added to any HTML representations of this step. This allows a step to provide links to external web pages, perhaps to provide detailed HTML code coverage results or other forms of build status.


Class Variable Details

parms

Value:
['name',
 'locks',
 'haltOnFailure',
 'flunkOnWarnings',
 'flunkOnFailure',
 'warnOnWarnings',
 'warnOnFailure',
 'alwaysRun',
...