RemoteCommands

Most of the action in build steps consists of performing operations on the slave. This is accomplished via RemoteCommand and its subclasses. Each represents a single operation on the slave.

Most data is returned to a command via updates. These updates are described in detail in Updates.

RemoteCommand

class buildbot.process.buildstep.RemoteCommand(remote_command, args, ignore_updates=False)

Parameters:

• remote_command (string) -- command to run on the slave
• args (dictionary) -- arguments to pass to the command
• ignore_updates -- true to ignore remote updates

This class handles running "raw" commands, consisting of a command name and a dictionary of arguments. If true, ignore_updates will suppress any updates sent from the slave.

There is seldom a need to use this class directly - in most cases, either LoggedRemoteCommand or RemoteShellCommand is the appropriate choice.

active

True if the command is currently running

run(step, remote)

Parameters:

• step -- the buildstep invoking this command
• remote -- a reference to the remote SlaveBuilder instance

Returns:

Deferred

Run the command. Call this method to initiate the command; the returned Deferred will fire when the command is complete. The Deferred fires with the RemoteCommand instance as its value.

interrupt(why)

Parameters:why (Twisted Failure) -- reason for interrupt Returns:Deferred

This method attempts to stop the running command early. The Deferred it returns will fire when the interrupt request is received by the slave; this may be a long time before the command itself completes, at which time the Deferred returned from run will fire.

The following methods are invoked from the slave. They should not be called directly.

remote_update(updates)

Parameters:updates -- new information from the slave

Handles updates from the slave on the running command. See Updates for the content of the updates. This class splits the updates out, and handles the ignore_updates option, then calls remoteUpdate to process the update.

remote_complete(failure=None)

Parameters:failure -- the failure that caused the step to complete, or None for success

Called by the slave to indicate that the command is complete. Normal completion (even with a nonzero rc) will finish with no failure; if failure is set, then the step should finish with status EXCEPTION.

These methods are hooks for subclasses to add functionality.

remoteUpdate(update)

Parameters:update -- the update to handle

Handle a single update. Subclasses must override this method.

remoteComplete(failure)

Parameters:failure -- the failure that caused the step to complete, or None for success Returns:Deferred

Handle command completion, performing any necessary cleanup. Subclasses should override this method. If failure is not None, it should be returned to ensure proper processing.

LoggedRemoteCommand

class buildbot.process.buildstep.LoggedRemoteCommand(remote_command, args, collectStdout=False, ignore_updates=False)

Parameters:

• remote_command (string) -- command to run on the slave
• args (dictionary) -- arguments to pass to the command
• collectStdout -- if True, collect the command's stdout
• ignore_updates -- true to ignore remote updates

This is a subclass of RemoteCommand which can handle log data from the slave-side command. This class handles updates for stdout, stderr, and header by appending them to a stdio logfile, if one is in use. It handles updates for rc by recording the value in its rc attribute.

Most slave-side commands, even those which do not spawn a new process on the slave, generate logs and an rc, requiring this class or one of its subclasses. See Updates for the updates that each command may send.

logs

A dictionary of LogFile instances representing active logs. Do not modify this directly -- use useLog instead.

rc

Set to the return code of the command, after the command has completed. For compatibility with shell commands, 0 is taken to indicate success, while nonzero return codes indicate failure.

stdout

If the collectStdout constructor argument is true, then this attribute will contain all data from stdout, as a single string. This is helpful when running informational commands (e.g., svnversion), but is not appropriate for commands that will produce a large amount of output, as that output is held in memory.

To set up logging, use useLog or useLogDelayed before starting the command:

useLog(log, closeWhenFinished=False, logfileName=None)

Parameters:

• log -- the LogFile instance to add to.
• closeWhenFinished -- if true, call finish when the command is finished.
• logfileName -- the name of the logfile, as given to the slave. This is stdio for standard streams.

Route log-related updates to the given logfile. Note that stdio is not included by default, and must be added explicitly. The logfileName must match the name given by the slave in any log updates.

useLogDelayed(log, logfileName, activateCallback, closeWhenFinished=False)

Parameters:

• log -- the LogFile instance to add to.
• logfileName -- the name of the logfile, as given to the slave. This is stdio for standard streams.
• activateCallback -- callback for when the log is added; see below
• closeWhenFinished -- if true, call finish when the command is finished.

Similar to useLog, but the logfile is only actually added when an update arrives for it. The callback, activateCallback, will be called with the RemoteCommand instance when the first update for the log is delivered.

With that finished, run the command using the inherited run method. During the run, you can inject data into the logfiles with any of these methods:

addStdout(data)

Parameters:data -- data to add to the logfile

Add stdout data to the stdio log.

addStderr(data)

Parameters:data -- data to add to the logfile

Add stderr data to the stdio log.

addHeader(data)

Parameters:data -- data to add to the logfile

Add header data to the stdio log.

addToLog(logname, data)

Parameters:

• logname -- the logfile to receive the data
• data -- data to add to the logfile

Add data to a logfile other than stdio.

class buildbot.process.buildstep.RemoteShellCommand(workdir, command, env=None, want_stdout=True, want_stderr=True, timeout=20*60, maxTime=None, logfiles={}, usePTY="slave-config", logEnviron=True, collectStdio=False)

Parameters:

• workdir -- directory in which command should be executed, relative to the builder's basedir.
• command (string or list) -- shell command to run
• want_stdout -- If false, then no updates will be sent for stdout.
• want_stderr -- If false, then no updates will be sent for stderr.
• timeout -- Maximum time without output before the command is killed.
• maxTime -- Maximum overall time from the start before the command is killed.
• env -- A dictionary of environment variables to augment or replace the existing environment on the slave.
• logfiles -- Additional logfiles to request from the slave.
• usePTY -- True to use a PTY, false to not use a PTY; the default value uses the default configured on the slave.
• logEnviron -- If false, do not log the environment on the slave.
• collectStdout -- If True, collect the command's stdout.

Most of the constructor arguments are sent directly to the slave; see shell for the details of the formats. The collectStdout parameter is as described for the parent class.

This class is used by the ShellCommand step, and by steps that run multiple customized shell commands.