buildbot.steps.shell.ShellCommand

Package buildbot :: Package steps :: Module shell :: Class ShellCommand

Class ShellCommand

   BuildStep --+    
               |    
LoggingBuildStep --+
                   |
                  ShellCommand

Known Subclasses:: BuildDebs, BuildEPYDoc, Compile, Configure, HLint, ProcessDocs, PyFlakes, RemovePYCs, Test, TreeSize, Trial

I run a single shell command on the buildslave. I return FAILURE if the exit code of that command is non-zero, SUCCESS otherwise. To change this behavior, override my .evaluateCommand method.

By default, a failure of this step will mark the whole build as FAILURE. To override this, give me an argument of flunkOnFailure=False .

I create a single Log named 'log' which contains the output of the command. To create additional summary Logs, override my .createSummary method.

The shell command I run (a list of argv strings) can be provided in several ways:

a class-level .command attribute
a command= parameter to my constructor (overrides .command)
set explicitly with my .setCommand() method (overrides both)

Method Summary
	`__init__(self, workdir, description, descriptionDone, command, **kwargs)`
	`checkForOldSlaveAndLogfiles(self)`
	`describe(self, done)` Return a list of short strings to describe this step, for the status display.
	`setCommand(self, command)`
	`setupEnvironment(self, cmd)`
	`start(self)` Begin the step.
Inherited from LoggingBuildStep
	`checkDisconnect(self, f)`
	`commandComplete(self, cmd)` This is a general-purpose hook method for subclasses.
	`createSummary(self, log)` To create summary logs, do something like this: warnings = grep('^Warning:', log.getText()) self.addCompleteLog('warnings', warnings)
	`evaluateCommand(self, cmd)` Decide whether the command was SUCCESS, WARNINGS, or FAILURE.
	`getColor(self, cmd, results)`
	`getText(self, cmd, results)`
	`getText2(self, cmd, results)` We have decided to add a short note about ourselves to the overall build description, probably because something went wrong.
	`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).
	`maybeGetText2(self, cmd, results)`
	`setStatus(self, cmd, results)`
	`setupLogfiles(self, cmd, logfiles)` Set up any additional logfiles= logs.
	`startCommand(self, cmd, errorMessages)`
Inherited from BuildStep
	`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)`
	`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)`
	`startStep(self, remote)` Begin the step.

Instance Variable Summary
`NoneType`	`command`: a list of argv strings (or WithProperties instances).
	`logfiles`: a dict mapping log NAMEs to workdir-relative FILENAMEs of their corresponding logfiles.
Inherited from BuildStep
`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
`NoneType`	`description` = None
`NoneType`	`descriptionDone` = None
`bool`	`flunkOnFailure` = `True`
`str`	`name` = `'shell'`
Inherited from LoggingBuildStep
`list`	`parms` = `['build', 'name', 'locks', 'haltOnFailure', 'flu...`
`tuple`	`progressMetrics` = `('output',)`
Inherited from BuildStep
`bool`	`flunkOnWarnings` = `False`
`bool`	`haltOnFailure` = `False`
`list`	`locks` = `[]`
`bool`	`useProgress` = `True`
`bool`	`warnOnFailure` = `False`
`bool`	`warnOnWarnings` = `False`

Method Details

describe(self, done=False)

Return a list of short strings to describe this step, for the status display. This uses the first few words of the shell command. You can replace this by setting .description in your subclass, or by overriding this method to describe the step better.

Parameters:: done - whether the command is complete or not, to improve the way the command is described. done=False is used while the command is still running, so a single imperfect-tense verb is appropriate ('compiling', 'testing', ...) done=True is used when the command has finished, and the default getText() method adds some text, so a simple noun is appropriate ('compile', 'tests' ...)
(type=boolean)

Overrides:: buildbot.process.buildstep.LoggingBuildStep.describe

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.

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

Instance Variable Details

command

a list of argv strings (or WithProperties instances). This will be used by start() to create a RemoteShellCommand instance.

Type:: NoneType
Value:: None

logfiles

a dict mapping log NAMEs to workdir-relative FILENAMEs of their corresponding logfiles. The contents of the file named FILENAME will be put into a LogFile named NAME, ina something approximating real-time. (note that logfiles= is actually handled by our parent class LoggingBuildStep)

Class Variable Details

description

Type:: NoneType
Value:: None

descriptionDone

Type:: NoneType
Value:: None

flunkOnFailure

Type:: bool
Value:: True

name

Type:: str
Value:: 'shell'

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

http://epydoc.sf.net