buildbot.process.buildstep.BuildStep

Package buildbot :: Package process :: Module buildstep :: Class BuildStep

Class BuildStep

Known Subclasses:: Dummy, FileDownload, FileUpload, LoggingBuildStep

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.

Method Summary
	`__init__(self, build, **kwargs)`
	`acquireLocks(self, res)`
	`addCompleteLog(self, name, text)`
	`addHTMLLog(self, name, html)`
	`addLog(self, name)`
	`addLogObserver(self, logname, observer)`
	`addURL(self, name, url)` Add a BuildStep URL to this step.
	`failed(self, why)`
	`finished(self, results)`
	`getProperty(self, propname)`
	`getSlaveName(self)`
	`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).
	`releaseLocks(self)`
	`runCommand(self, c)`
	`setProgress(self, metric, value)` BuildSteps can call self.setProgress() to announce progress along some metric.
	`setProperty(self, propname, value)`
	`setStepStatus(self, step_status)`
	`setupProgress(self)`
	`slaveVersion(self, command, oldversion)` Return the version number of the given slave command.
	`slaveVersionIsOlderThan(self, command, minversion)`
	`start(self)` Begin the step.
	`startStep(self, remote)` Begin the step.

Instance Variable Summary
`buildbot.process.base.Build`	`build`: the parent Build which is executing this step
`buildbot.status.progress.StepProgress`	`progress`: tracks ETA for the step
`buildbot.status.builder.BuildStepStatus`	`step_status`: collects output status

Class Variable Summary
`bool`	`flunkOnFailure` = `False`
`bool`	`flunkOnWarnings` = `False`
`bool`	`haltOnFailure` = `False`
`list`	`locks` = `[]`
`str`	`name` = `'generic'`
`list`	`parms` = `['build', 'name', 'locks', 'haltOnFailure', 'flu...`
`tuple`	`progressMetrics` = `()`
`bool`	`useProgress` = `True`
`bool`	`warnOnFailure` = `False`
`bool`	`warnOnWarnings` = `False`

Method Details

addURL(self, name, url)

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.

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). 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']

setProgress(self, metric, value)

BuildSteps can call self.setProgress() to announce progress along some metric.

slaveVersion(self, command, oldversion=None)

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.

start(self)

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.setColor('red')
 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.

startStep(self, remote)

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:: remote - a reference to the slave's buildbot.slave.bot.SlaveBuilder instance where any RemoteCommands may be run
(type=twisted.spread.pb.RemoteReference)

Instance Variable Details

build

the parent Build which is executing this step

Type:: buildbot.process.base.Build
Value:: None

progress

tracks ETA for the step

Type:: buildbot.status.progress.StepProgress
Value:: None

step_status

collects output status

Type:: buildbot.status.builder.BuildStepStatus
Value:: None

Class Variable Details

flunkOnFailure

Type:: bool
Value:: False

flunkOnWarnings

Type:: bool
Value:: False

haltOnFailure

Type:: bool
Value:: False

locks

Type:: list
Value:: []

name

Type:: str
Value:: 'generic'

parms

Type:: list
Value:: ['build', 'name', 'locks', 'haltOnFailure', 'flunkOnWarnings', 'flunkOnFailure', 'warnOnWarnings', 'warnOnFailure', ...

progressMetrics

Type:: tuple
Value:: ()

useProgress

Type:: bool
Value:: True

warnOnFailure

Type:: bool
Value:: False

warnOnWarnings

Type:: bool
Value:: False

Generated by Epydoc 2.1 on Sun Dec 10 22:04:45 2006

http://epydoc.sf.net