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

Class BuildStep

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', runtime=True) 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:

remote (twisted.spread.pb.RemoteReference) - a reference to the slave's buildbot.slave.bot.SlaveBuilder instance where any RemoteCommands may be run

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',
...