Package buildbot :: Package steps :: Module blocker :: Class Blocker
[frames] | no frames]

Class Blocker

source code

process.buildstep.BuildStep --+

Build step that blocks until at least one other step finishes.

@ivar upstreamSteps: a non-empty list of (builderName, stepName) tuples
                     identifying the other build steps that must
                     complete in order to unblock this Blocker.
@ivar idlePolicy: string: what to do if one of the upstream builders is
                  idle when this Blocker starts; one of:
                    "error": just blow up (the Blocker will fail with
                      status EXCEPTION)
                    "ignore": carry on as if the referenced build step
                      was not mentioned (or is already complete)
                    "block": block until the referenced builder starts
                      a build, and then block until the referenced build
                      step in that build finishes
@ivar timeout: int: how long to block, in seconds, before giving up and
               failing (default: None, meaning block forever)

Instance Methods
__init__(self, **kwargs) source code
__str__(self) source code
__repr__(self) source code
buildsMatch(self, buildStatus1, buildStatus2)
Return true if buildStatus1 and buildStatus2 are from related builds, i.e.
source code
Begin the step.
source code

Inherited from process.buildstep.BuildStep: acquireLocks, addCompleteLog, addFactoryArguments, addHTMLLog, addLog, addLogObserver, addURL, describe, failed, finished, getLog, getProperty, getSlaveName, getStepFactory, interrupt, releaseLocks, runCommand, setBuild, setBuildSlave, setDefaultWorkdir, setProgress, setProperty, setStepStatus, setupProgress, slaveVersion, slaveVersionIsOlderThan, startStep

Class Variables
  parms = ['name', 'locks', 'haltOnFailure', 'flunkOnWarnings', ...
  flunkOnFailure = True
  upstreamSteps = None
  idlePolicy = 'block'
  timeout = None
  VALID_IDLE_POLICIES = ('error', 'ignore', 'block')

Inherited from process.buildstep.BuildStep: alwaysRun, doStepIf, flunkOnWarnings, haltOnFailure, locks, name, progressMetrics, useProgress, warnOnFailure, warnOnWarnings

Instance Variables

Inherited from process.buildstep.BuildStep: build, progress, step_status

Method Details

__init__(self, **kwargs)

source code 
Overrides: process.buildstep.BuildStep.__init__

buildsMatch(self, buildStatus1, buildStatus2)

source code 

Return true if buildStatus1 and buildStatus2 are from related builds, i.e. a Blocker step running in buildStatus2 should be blocked by an upstream step in buildStatus1. Return false if they are unrelated.

Default implementation simply raises NotImplementedError: you *must* subclass Blocker and implement this method, because BuildBot currently provides no way to relate different builders. This might change if ticket #875 ("build flocks") is implemented.


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)

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

Overrides: process.buildstep.BuildStep.start
(inherited documentation)

Class Variable Details