<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Master-Slave API — Buildbot 0.8.12 documentation</title>
<link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.12',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/buildbot.ico"/>
<link rel="top" title="Buildbot 0.8.12 documentation" href="../index.html" />
<link rel="up" title="Buildbot Development" href="index.html" />
<link rel="next" title="String Encodings" href="encodings.html" />
<link rel="prev" title="Web Status" href="webstatus.html" />
</head>
<body role="document">
<div class="header-wrapper" role="banner">
<div class="header">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/header-text-transparent.png" alt="Logo"/>
</a></p>
<div class="headertitle"><a
href="../index.html">Buildbot 0.8.12 documentation</a></div>
<div class="rel" role="navigation" aria-label="related navigation">
<a href="webstatus.html" title="Web Status"
accesskey="P">previous</a> |
<a href="encodings.html" title="String Encodings"
accesskey="N">next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
accesskey="I">index</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="master-slave-api">
<h1>Master-Slave API<a class="headerlink" href="#master-slave-api" title="Permalink to this headline">¶</a></h1>
<p>This section describes the master-slave interface.</p>
<div class="section" id="connection">
<h2>Connection<a class="headerlink" href="#connection" title="Permalink to this headline">¶</a></h2>
<p>The interface is based on Twisted's Perspective Broker, which operates over TCP
connections.</p>
<p>The slave connects to the master, using the parameters supplied to
<strong class="command">buildslave create-slave</strong>. It uses a reconnecting process with an
exponential backoff, and will automatically reconnect on disconnection.</p>
<p>Once connected, the slave authenticates with the Twisted Cred (newcred)
mechanism, using the username and password supplied to <strong class="command">buildslave
create-slave</strong>. The <em>mind</em> is the slave bot instance (class
<code class="xref py py-class docutils literal"><span class="pre">buildslave.bot.Bot</span></code>).</p>
<p>On the master side, the realm is implemented by
<code class="xref py py-class docutils literal"><span class="pre">buildbot.master.Dispatcher</span></code>, which examines the username of incoming
avatar requests. There are special cases for <code class="docutils literal"><span class="pre">change</span></code>, <code class="docutils literal"><span class="pre">debug</span></code>, and
<code class="docutils literal"><span class="pre">statusClient</span></code>, which are not discussed here. For all other usernames,
the botmaster is consulted, and if a slave with that name is configured, its
<code class="xref py py-class docutils literal"><span class="pre">buildbot.buildslave.BuildSlave</span></code> instance is returned as the perspective.</p>
</div>
<div class="section" id="build-slaves">
<h2>Build Slaves<a class="headerlink" href="#build-slaves" title="Permalink to this headline">¶</a></h2>
<p>At this point, the master-side BuildSlave object has a pointer to the remote,
slave-side Bot object in its <code class="docutils literal"><span class="pre">self.slave</span></code>, and the slave-side Bot object has
a reference to the master-side BuildSlave object in its <code class="docutils literal"><span class="pre">self.perspective</span></code>.</p>
<div class="section" id="bot-methods">
<h3>Bot methods<a class="headerlink" href="#bot-methods" title="Permalink to this headline">¶</a></h3>
<p>The slave-side Bot object has the following remote methods:</p>
<dl class="docutils">
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_getCommands</span></code></dt>
<dd>Returns a list of <code class="docutils literal"><span class="pre">(name,</span> <span class="pre">version)</span></code> for all commands the slave recognizes</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_setBuilderList</span></code></dt>
<dd><p class="first">Given a list of builders and their build directories, ensures that
those builders, and only those builders, are running. This can be
called after the initial connection is established, with a new
list, to add or remove builders.</p>
<p class="last">This method returns a dictionary of <code class="xref py py-class docutils literal"><span class="pre">SlaveBuilder</span></code> objects - see below</p>
</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_print</span></code></dt>
<dd>Adds a message to the slave logfile</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_getSlaveInfo</span></code></dt>
<dd><p class="first">Returns the contents of the slave's <code class="file docutils literal"><span class="pre">info/</span></code> directory. This also
contains the keys</p>
<dl class="last docutils">
<dt><code class="docutils literal"><span class="pre">environ</span></code></dt>
<dd>copy of the slaves environment</dd>
<dt><code class="docutils literal"><span class="pre">system</span></code></dt>
<dd>OS the slave is running (extracted from Python's os.name)</dd>
<dt><code class="docutils literal"><span class="pre">basedir</span></code></dt>
<dd>base directory where slave is running</dd>
</dl>
</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_getVersion</span></code></dt>
<dd>Returns the slave's version</dd>
</dl>
</div>
<div class="section" id="buildslave-methods">
<h3>BuildSlave methods<a class="headerlink" href="#buildslave-methods" title="Permalink to this headline">¶</a></h3>
<p>The master-side object has the following method:</p>
<dl class="docutils">
<dt><code class="xref py py-meth docutils literal"><span class="pre">perspective_keepalive</span></code></dt>
<dd>Does nothing - used to keep traffic flowing over the TCP connection</dd>
</dl>
</div>
</div>
<div class="section" id="setup">
<h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2>
<p>After the initial connection and trading of a mind (Bot) for an avatar
(BuildSlave), the master calls the Bot's <code class="xref py py-meth docutils literal"><span class="pre">setBuilderList</span></code> method to set
up the proper slave builders on the slave side. This method returns a
reference to each of the new slave-side <code class="xref py py-class docutils literal"><span class="pre">SlaveBuilder</span></code>
objects, described below. Each of these is handed to the corresponding
master-side <code class="xref py py-class docutils literal"><span class="pre">SlaveBuilder</span></code> object.</p>
<p>This immediately calls the remote <code class="xref py py-meth docutils literal"><span class="pre">setMaster</span></code> method, then the
<code class="xref py py-meth docutils literal"><span class="pre">print</span></code> method.</p>
</div>
<div class="section" id="pinging">
<h2>Pinging<a class="headerlink" href="#pinging" title="Permalink to this headline">¶</a></h2>
<p>To ping a remote SlaveBuilder, the master calls its <code class="xref py py-meth docutils literal"><span class="pre">print</span></code> method.</p>
</div>
<div class="section" id="building">
<h2>Building<a class="headerlink" href="#building" title="Permalink to this headline">¶</a></h2>
<p>When a build starts, the master calls the slave's <code class="xref py py-meth docutils literal"><span class="pre">startBuild</span></code> method.
Each BuildStep instance will subsequently call the <code class="xref py py-meth docutils literal"><span class="pre">startCommand</span></code> method,
passing a reference to itself as the <code class="docutils literal"><span class="pre">stepRef</span></code> parameter. The
<code class="xref py py-meth docutils literal"><span class="pre">startCommand</span></code> method returns immediately, and the end of the command is
signalled with a call to a method on the master-side BuildStep object.</p>
</div>
<div class="section" id="slave-builders">
<h2>Slave Builders<a class="headerlink" href="#slave-builders" title="Permalink to this headline">¶</a></h2>
<p>Each build slave has a set of builders which can run on it. These are
represented by distinct classes on the master and slave, just like the
BuildSlave and Bot objects described above.</p>
<p>On the slave side, builders are represented as instances of the
<code class="xref py py-class docutils literal"><span class="pre">buildslave.bot.SlaveBuilder</span></code> class. On the master side, they are
represented by the <code class="xref py py-class docutils literal"><span class="pre">buildbot.process.slavebuilder.SlaveBuilder</span></code> class.
The identical names are a source of confusion. The following will refer to
these as the slave-side and master-side SlaveBuilder classes. Each object
keeps a reference to its opposite in <code class="docutils literal"><span class="pre">self.remote</span></code>.</p>
<div class="section" id="slave-side-slavebuilder-methods">
<h3>Slave-Side SlaveBuilder Methods<a class="headerlink" href="#slave-side-slavebuilder-methods" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_setMaster</span></code></dt>
<dd>Provides a reference to the master-side SlaveBuilder</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_print</span></code></dt>
<dd>Adds a message to the slave logfile; used to check round-trip connectivity</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_startBuild</span></code></dt>
<dd>Indicates that a build is about to start, and that any subsequent
commands are part of that build</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_startCommand</span></code></dt>
<dd>Invokes a command on the slave side</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_interruptCommand</span></code></dt>
<dd>Interrupts the currently-running command</dd>
<dt><code class="xref py py-meth docutils literal"><span class="pre">remote_shutdown</span></code></dt>
<dd>Shuts down the slave cleanly</dd>
</dl>
</div>
<div class="section" id="master-side-slavebuilder-methods">
<h3>Master-side SlaveBuilder Methods<a class="headerlink" href="#master-side-slavebuilder-methods" title="Permalink to this headline">¶</a></h3>
<p>The master side does not have any remotely-callable methods.</p>
</div>
</div>
<div class="section" id="commands">
<h2>Commands<a class="headerlink" href="#commands" title="Permalink to this headline">¶</a></h2>
<p>Actual work done by the slave is represented on the master side by a
<a class="reference internal" href="cls-remotecommands.html#buildbot.process.buildstep.RemoteCommand" title="buildbot.process.buildstep.RemoteCommand"><code class="xref py py-class docutils literal"><span class="pre">buildbot.process.buildstep.RemoteCommand</span></code></a> instance.</p>
<p>The command instance keeps a reference to the slave-side
<code class="xref py py-class docutils literal"><span class="pre">buildslave.bot.SlaveBuilder</span></code>, and calls methods like
<code class="xref py py-meth docutils literal"><span class="pre">remote_startCommand</span></code> to start new commands.
Once that method is called, the <code class="xref py py-class docutils literal"><span class="pre">SlaveBuilder</span></code> instance
keeps a reference to the command, and calls the following methods on it:</p>
<div class="section" id="master-side-remotecommand-methods">
<h3>Master-Side RemoteCommand Methods<a class="headerlink" href="#master-side-remotecommand-methods" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><a class="reference internal" href="cls-remotecommands.html#buildbot.process.buildstep.RemoteCommand.remote_update" title="buildbot.process.buildstep.RemoteCommand.remote_update"><code class="xref py py-meth docutils literal"><span class="pre">remote_update</span></code></a></dt>
<dd>Update information about the running command. See below for the format.</dd>
<dt><a class="reference internal" href="cls-remotecommands.html#buildbot.process.buildstep.RemoteCommand.remote_complete" title="buildbot.process.buildstep.RemoteCommand.remote_complete"><code class="xref py py-meth docutils literal"><span class="pre">remote_complete</span></code></a></dt>
<dd>Signal that the command is complete, either successfully or with a Twisted failure.</dd>
</dl>
</div>
</div>
<div class="section" id="updates">
<span id="master-slave-updates"></span><h2>Updates<a class="headerlink" href="#updates" title="Permalink to this headline">¶</a></h2>
<p>Updates from the slave, sent via
<a class="reference internal" href="cls-remotecommands.html#buildbot.process.buildstep.RemoteCommand.remote_update" title="buildbot.process.buildstep.RemoteCommand.remote_update"><code class="xref py py-meth docutils literal"><span class="pre">remote_update</span></code></a>, are a list of
individual update elements. Each update element is, in turn, a list of the
form <code class="docutils literal"><span class="pre">[data,</span> <span class="pre">0]</span></code> where the 0 is present for historical reasons. The data is
a dictionary, with keys describing the contents. The updates are handled by
<a class="reference internal" href="cls-remotecommands.html#buildbot.process.buildstep.RemoteCommand.remoteUpdate" title="buildbot.process.buildstep.RemoteCommand.remoteUpdate"><code class="xref py py-meth docutils literal"><span class="pre">remoteUpdate</span></code></a>.</p>
<p>Updates with different keys can be combined into a single dictionary or
delivered sequentially as list elements, at the slave's option.</p>
<p>To summarize, an <code class="docutils literal"><span class="pre">updates</span></code> parameter to
<a class="reference internal" href="cls-remotecommands.html#buildbot.process.buildstep.RemoteCommand.remote_update" title="buildbot.process.buildstep.RemoteCommand.remote_update"><code class="xref py py-meth docutils literal"><span class="pre">remote_update</span></code></a> might look like
this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span>
<span class="p">[</span> <span class="p">{</span> <span class="s1">'header'</span> <span class="p">:</span> <span class="s1">'running command..'</span> <span class="p">},</span> <span class="mi">0</span> <span class="p">],</span>
<span class="p">[</span> <span class="p">{</span> <span class="s1">'stdout'</span> <span class="p">:</span> <span class="s1">'abcd'</span><span class="p">,</span> <span class="s1">'stderr'</span> <span class="p">:</span> <span class="s1">'local modifications'</span> <span class="p">},</span> <span class="mi">0</span> <span class="p">],</span>
<span class="p">[</span> <span class="p">{</span> <span class="s1">'log'</span> <span class="p">:</span> <span class="p">(</span> <span class="s1">'cmd.log'</span><span class="p">,</span> <span class="s1">'cmd invoked at 12:33 pm</span><span class="se">\n</span><span class="s1">'</span> <span class="p">)</span> <span class="p">},</span> <span class="mi">0</span> <span class="p">],</span>
<span class="p">[</span> <span class="p">{</span> <span class="s1">'rc'</span> <span class="p">:</span> <span class="mi">0</span> <span class="p">},</span> <span class="mi">0</span> <span class="p">],</span>
<span class="p">]</span>
</pre></div>
</div>
<div class="section" id="defined-commands">
<h3>Defined Commands<a class="headerlink" href="#defined-commands" title="Permalink to this headline">¶</a></h3>
<p>The following commands are defined on the slaves.</p>
<div class="section" id="shell">
<span id="shell-command-args"></span><h4>shell<a class="headerlink" href="#shell" title="Permalink to this headline">¶</a></h4>
<p>Runs a shell command on the slave. This command takes the following arguments:</p>
<p><code class="docutils literal"><span class="pre">command</span></code></p>
<blockquote>
<div>The command to run. If this is a string, will be passed to the system
shell as a string. Otherwise, it must be a list, which will be
executed directly.</div></blockquote>
<p><code class="docutils literal"><span class="pre">workdir</span></code></p>
<blockquote>
<div>Directory in which to run the command, relative to the builder dir.</div></blockquote>
<p><code class="docutils literal"><span class="pre">env</span></code></p>
<blockquote>
<div>A dictionary of environment variables to augment or replace the
existing environment on the slave. In this dictionary, <code class="docutils literal"><span class="pre">PYTHONPATH</span></code>
is treated specially: it should be a list of path components, rather
than a string, and will be prepended to the existing Python path.</div></blockquote>
<p><code class="docutils literal"><span class="pre">initial_stdin</span></code></p>
<blockquote>
<div>A string which will be written to the command's standard input before
it is closed.</div></blockquote>
<p><code class="docutils literal"><span class="pre">want_stdout</span></code></p>
<blockquote>
<div>If false, then no updates will be sent for stdout.</div></blockquote>
<p><code class="docutils literal"><span class="pre">want_stderr</span></code></p>
<blockquote>
<div>If false, then no updates will be sent for stderr.</div></blockquote>
<p><code class="docutils literal"><span class="pre">usePTY</span></code></p>
<blockquote>
<div>If true, the command should be run with a PTY (POSIX only). This
defaults to the value specified in the slave's <code class="docutils literal"><span class="pre">buildbot.tac</span></code>.</div></blockquote>
<p><code class="docutils literal"><span class="pre">not_really</span></code></p>
<blockquote>
<div>If true, skip execution and return an update with rc=0.</div></blockquote>
<p><code class="docutils literal"><span class="pre">timeout</span></code></p>
<blockquote>
<div>Maximum time without output before the command is killed.</div></blockquote>
<p><code class="docutils literal"><span class="pre">maxTime</span></code></p>
<blockquote>
<div>Maximum overall time from the start before the command is killed.</div></blockquote>
<p><code class="docutils literal"><span class="pre">logfiles</span></code></p>
<blockquote>
<div><p>A dictionary specifying logfiles other than stdio. Keys are the logfile
names, and values give the workdir-relative filename of the logfile. Alternately,
a value can be a dictionary; in this case, the dictionary must have a <code class="docutils literal"><span class="pre">filename</span></code>
key specifying the filename, and can also have the following keys:</p>
<p><code class="docutils literal"><span class="pre">follow</span></code></p>
<blockquote>
<div>Only follow the file from its current end-of-file, rather that starting
from the beginning.</div></blockquote>
</div></blockquote>
<p><code class="docutils literal"><span class="pre">logEnviron</span></code></p>
<blockquote>
<div>If false, the command's environment will not be logged.</div></blockquote>
<p>The <code class="docutils literal"><span class="pre">shell</span></code> command sends the following updates:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">stdout</span></code></dt>
<dd>The data is a bytestring which represents a continuation of the stdout
stream. Note that the bytestring boundaries are not necessarily aligned
with newlines.</dd>
<dt><code class="docutils literal"><span class="pre">stderr</span></code></dt>
<dd>Similar to <code class="docutils literal"><span class="pre">stdout</span></code>, but for the error stream.</dd>
<dt><code class="docutils literal"><span class="pre">header</span></code></dt>
<dd>Similar to <code class="docutils literal"><span class="pre">stdout</span></code>, but containing data for a stream of
buildbot-specific metadata.</dd>
<dt><code class="docutils literal"><span class="pre">rc</span></code></dt>
<dd>The exit status of the command, where -- in keeping with UNIX tradition --
0 indicates success and any nonzero value is considered a failure. No
further updates should be sent after an <code class="docutils literal"><span class="pre">rc</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">log</span></code></dt>
<dd>This update contains data for a logfile other than stdio. The data
associated with the update is a tuple of the log name and the data for that
log. Note that non-stdio logs do not distinguish output, error, and header
streams.</dd>
</dl>
</div>
<div class="section" id="uploadfile">
<h4>uploadFile<a class="headerlink" href="#uploadfile" title="Permalink to this headline">¶</a></h4>
<p>Upload a file from the slave to the master. The arguments are</p>
<p><code class="docutils literal"><span class="pre">workdir</span></code></p>
<blockquote>
<div>The base directory for the filename, relative to the builder's basedir.</div></blockquote>
<p><code class="docutils literal"><span class="pre">slavesrc</span></code></p>
<blockquote>
<div>Name of the filename to read from., relative to the workdir.</div></blockquote>
<p><code class="docutils literal"><span class="pre">writer</span></code></p>
<blockquote>
<div>A remote reference to a writer object, described below.</div></blockquote>
<p><code class="docutils literal"><span class="pre">maxsize</span></code></p>
<blockquote>
<div>Maximum size, in bytes, of the file to write. The operation will fail if
the file exceeds this size.</div></blockquote>
<p><code class="docutils literal"><span class="pre">blocksize</span></code></p>
<blockquote>
<div>The block size with which to transfer the file.</div></blockquote>
<p><code class="docutils literal"><span class="pre">keepstamp</span></code></p>
<blockquote>
<div>If true, preserve the file modified and accessed times.</div></blockquote>
<p>The slave calls a few remote methods on the writer object. First, the
<code class="docutils literal"><span class="pre">write</span></code> method is called with a bytestring containing data, until all of the
data has been transmitted. Then, the slave calls the writer's <code class="docutils literal"><span class="pre">close</span></code>,
followed (if <code class="docutils literal"><span class="pre">keepstamp</span></code> is true) by a call to <code class="docutils literal"><span class="pre">upload(atime,</span> <span class="pre">mtime)</span></code>.</p>
<p>This command sends <code class="docutils literal"><span class="pre">rc</span></code> and <code class="docutils literal"><span class="pre">stderr</span></code> updates, as defined for the <code class="docutils literal"><span class="pre">shell</span></code>
command.</p>
</div>
<div class="section" id="uploaddirectory">
<h4>uploadDirectory<a class="headerlink" href="#uploaddirectory" title="Permalink to this headline">¶</a></h4>
<p>Similar to <code class="docutils literal"><span class="pre">uploadFile</span></code>, this command will upload an entire directory to the
master, in the form of a tarball. It takes the following arguments:</p>
<p><code class="docutils literal"><span class="pre">workdir</span></code>
<code class="docutils literal"><span class="pre">slavesrc</span></code>
<code class="docutils literal"><span class="pre">writer</span></code>
<code class="docutils literal"><span class="pre">maxsize</span></code>
<code class="docutils literal"><span class="pre">blocksize</span></code></p>
<blockquote>
<div>See <code class="docutils literal"><span class="pre">uploadFile</span></code></div></blockquote>
<p><code class="docutils literal"><span class="pre">compress</span></code></p>
<blockquote>
<div>Compression algorithm to use -- one of <code class="docutils literal"><span class="pre">None</span></code>, <code class="docutils literal"><span class="pre">'bz2'</span></code>, or <code class="docutils literal"><span class="pre">'gz'</span></code>.</div></blockquote>
<p>The writer object is treated similarly to the <code class="docutils literal"><span class="pre">uploadFile</span></code> command, but after
the file is closed, the slave calls the master's <code class="docutils literal"><span class="pre">unpack</span></code> method with no
arguments to extract the tarball.</p>
<p>This command sends <code class="docutils literal"><span class="pre">rc</span></code> and <code class="docutils literal"><span class="pre">stderr</span></code> updates, as defined for the <code class="docutils literal"><span class="pre">shell</span></code>
command.</p>
</div>
<div class="section" id="downloadfile">
<h4>downloadFile<a class="headerlink" href="#downloadfile" title="Permalink to this headline">¶</a></h4>
<p>This command will download a file from the master to the slave. It takes the
following arguments:</p>
<p><code class="docutils literal"><span class="pre">workdir</span></code></p>
<blockquote>
<div>Base directory for the destination filename, relative to the builder basedir.</div></blockquote>
<p><code class="docutils literal"><span class="pre">slavedest</span></code></p>
<blockquote>
<div>Filename to write to, relative to the workdir.</div></blockquote>
<p><code class="docutils literal"><span class="pre">reader</span></code></p>
<blockquote>
<div>A remote reference to a reader object, described below.</div></blockquote>
<p><code class="docutils literal"><span class="pre">maxsize</span></code></p>
<blockquote>
<div>Maximum size of the file.</div></blockquote>
<p><code class="docutils literal"><span class="pre">blocksize</span></code></p>
<blockquote>
<div>The block size with which to transfer the file.</div></blockquote>
<p><code class="docutils literal"><span class="pre">mode</span></code></p>
<blockquote>
<div>Access mode for the new file.</div></blockquote>
<p>The reader object's <code class="docutils literal"><span class="pre">read(maxsize)</span></code> method will be called with a maximum
size, which will return no more than that number of bytes as a bytestring. At
EOF, it will return an empty string. Once EOF is received, the slave will call
the remote <code class="docutils literal"><span class="pre">close</span></code> method.</p>
<p>This command sends <code class="docutils literal"><span class="pre">rc</span></code> and <code class="docutils literal"><span class="pre">stderr</span></code> updates, as defined for the <code class="docutils literal"><span class="pre">shell</span></code>
command.</p>
</div>
<div class="section" id="mkdir">
<h4>mkdir<a class="headerlink" href="#mkdir" title="Permalink to this headline">¶</a></h4>
<p>This command will create a directory on the slave. It will also create any
intervening directories required. It takes the following argument:</p>
<p><code class="docutils literal"><span class="pre">dir</span></code></p>
<blockquote>
<div>Directory to create.</div></blockquote>
<p>The <code class="docutils literal"><span class="pre">mkdir</span></code> command produces the same updates as <code class="docutils literal"><span class="pre">shell</span></code>.</p>
</div>
<div class="section" id="rmdir">
<h4>rmdir<a class="headerlink" href="#rmdir" title="Permalink to this headline">¶</a></h4>
<p>This command will remove a directory or file on the slave. It takes the following arguments:</p>
<p><code class="docutils literal"><span class="pre">dir</span></code></p>
<blockquote>
<div>Directory to remove.</div></blockquote>
<p><code class="docutils literal"><span class="pre">timeout</span></code>
<code class="docutils literal"><span class="pre">maxTime</span></code></p>
<blockquote>
<div>See <code class="docutils literal"><span class="pre">shell</span></code>, above.</div></blockquote>
<p>The <code class="docutils literal"><span class="pre">rmdir</span></code> command produces the same updates as <code class="docutils literal"><span class="pre">shell</span></code>.</p>
</div>
<div class="section" id="cpdir">
<h4>cpdir<a class="headerlink" href="#cpdir" title="Permalink to this headline">¶</a></h4>
<p>This command will copy a directory from place to place on the slave. It takes the following
arguments:</p>
<p><code class="docutils literal"><span class="pre">fromdir</span></code></p>
<blockquote>
<div>Source directory for the copy operation, relative to the builder's basedir.</div></blockquote>
<p><code class="docutils literal"><span class="pre">todir</span></code></p>
<blockquote>
<div>Destination directory for the copy operation, relative to the builder's basedir.</div></blockquote>
<p><code class="docutils literal"><span class="pre">timeout</span></code>
<code class="docutils literal"><span class="pre">maxTime</span></code></p>
<blockquote>
<div>See <code class="docutils literal"><span class="pre">shell</span></code>, above.</div></blockquote>
<p>The <code class="docutils literal"><span class="pre">cpdir</span></code> command produces the same updates as <code class="docutils literal"><span class="pre">shell</span></code>.</p>
</div>
<div class="section" id="stat">
<h4>stat<a class="headerlink" href="#stat" title="Permalink to this headline">¶</a></h4>
<p>This command returns status information about a file or directory. It takes a
single parameter, <code class="docutils literal"><span class="pre">file</span></code>, specifying the filename relative to the builder's
basedir.</p>
<p>It produces two status updates:</p>
<p><code class="docutils literal"><span class="pre">stat</span></code></p>
<blockquote>
<div>The return value from Python's <code class="docutils literal"><span class="pre">os.stat</span></code>.</div></blockquote>
<p><code class="docutils literal"><span class="pre">rc</span></code></p>
<blockquote>
<div>0 if the file is found, otherwise 1.</div></blockquote>
</div>
<div class="section" id="glob">
<h4>glob<a class="headerlink" href="#glob" title="Permalink to this headline">¶</a></h4>
<p>This command finds all pathnames matching a specified pattern that uses shell-style wildcards.
It takes a single parameter, <code class="docutils literal"><span class="pre">pathname</span></code>, specifying the pattern to pass to Python's
<code class="docutils literal"><span class="pre">glob.glob</span></code> function.</p>
<p>It produces two status updates:</p>
<p><code class="docutils literal"><span class="pre">files</span></code></p>
<blockquote>
<div>The list of matching files returned from <code class="docutils literal"><span class="pre">glob.glob</span></code></div></blockquote>
<p><code class="docutils literal"><span class="pre">rc</span></code></p>
<blockquote>
<div>0 if the <code class="docutils literal"><span class="pre">glob.glob</span></code> does not raise exception, otherwise 1.</div></blockquote>
</div>
<div class="section" id="listdir">
<h4>listdir<a class="headerlink" href="#listdir" title="Permalink to this headline">¶</a></h4>
<p>This command reads the directory and returns the list with directory contents. It
takes a single parameter, <code class="docutils literal"><span class="pre">dir</span></code>, specifying the directory relative to builder's basedir.</p>
<p>It produces two status updates:</p>
<p><code class="docutils literal"><span class="pre">files</span></code></p>
<blockquote>
<div>The list of files in the directory returned from <code class="docutils literal"><span class="pre">os.listdir</span></code></div></blockquote>
<p><code class="docutils literal"><span class="pre">rc</span></code></p>
<blockquote>
<div>0 if the <code class="docutils literal"><span class="pre">os.listdir</span></code> does not raise exception, otherwise 1.</div></blockquote>
</div>
<div class="section" id="source-commands">
<h4>Source Commands<a class="headerlink" href="#source-commands" title="Permalink to this headline">¶</a></h4>
<p>The source commands (<code class="docutils literal"><span class="pre">bk</span></code>, <code class="docutils literal"><span class="pre">cvs</span></code>, <code class="docutils literal"><span class="pre">darcs</span></code>, <code class="docutils literal"><span class="pre">git</span></code>, <code class="docutils literal"><span class="pre">repo</span></code>, <code class="docutils literal"><span class="pre">bzr</span></code>,
<code class="docutils literal"><span class="pre">hg</span></code>, <code class="docutils literal"><span class="pre">p4</span></code>, <code class="docutils literal"><span class="pre">p4sync</span></code>, and <code class="docutils literal"><span class="pre">mtn</span></code>) are deprecated. See the docstrings in
the source code for more information.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Buildbot Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../manual/index.html">Buildbot Manual</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Buildbot Development</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="master-overview.html">Master Organization</a></li>
<li class="toctree-l2"><a class="reference internal" href="definitions.html">Definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style.html">Buildbot Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="tests.html">Buildbot's Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="utils.html">Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="database.html">Database</a></li>
<li class="toctree-l2"><a class="reference internal" href="results.html">Build Result Codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="formats.html">File Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="webstatus.html">Web Status</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Master-Slave API</a><ul class="simple">
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="encodings.html">String Encodings</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="plugins-publish.html">How to package Buildbot plugins</a></li>
<li class="toctree-l2"><a class="reference internal" href="classes.html">Classes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes/index.html">Release Notes for Buildbot 0.8.12</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="webstatus.html" title="Web Status"
>previous</a> |
<a href="encodings.html" title="String Encodings"
>next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
>index</a>
</div>
<div role="note" aria-label="source link">
<br/>
<a href="../_sources/developer/master-slave.txt"
rel="nofollow">Show Source</a>
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.1.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
