<!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>Command-line Tool — Buildbot 0.8.9 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.9',
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.9 documentation" href="../index.html" />
<link rel="up" title="Buildbot Manual" href="index.html" />
<link rel="next" title="Resources" href="resources.html" />
<link rel="prev" title="New-Style Build Steps" href="new-style-steps.html" />
</head>
<body>
<div class="header-wrapper">
<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.9 documentation</a></div>
<div class="rel">
<a href="new-style-steps.html" title="New-Style Build Steps"
accesskey="P">previous</a> |
<a href="resources.html" title="Resources"
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">
<div class="section" id="command-line-tool">
<span id="id1"></span><h1>Command-line Tool<a class="headerlink" href="#command-line-tool" title="Permalink to this headline">¶</a></h1>
<p>This section describes command-line tools available after buildbot
installation. Since version 0.8 the one-for-all <strong class="command">buildbot</strong>
command-line tool was divided into two parts namely <strong class="command">buildbot</strong>
and <strong class="command">buildslave</strong>. The last one was separated from main
command-line tool to minimize dependencies required for running a
buildslave while leaving all other functions to <strong class="command">buildbot</strong> tool.</p>
<p>Every command-line tool has a list of global options and a set of commands
which have their own options. One can run these tools in the following way:</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot [global options] command [command options]
buildslave [global options] command [command options]
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">buildbot</span></tt> command is used on the master, while <tt class="docutils literal"><span class="pre">buildslave</span></tt> is used on
the slave. Global options are the same for both tools which perform the
following actions:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">--help</span></kbd></td>
<td>Print general help about available commands and global options and exit.
All subsequent arguments are ignored.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--verbose</span></kbd></td>
<td>Set verbose output.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--version</span></kbd></td>
<td>Print current buildbot version and exit. All subsequent arguments are
ignored.</td></tr>
</tbody>
</table>
<p>You can get help on any command by specifying <tt class="docutils literal"><span class="pre">--help</span></tt> as a
command option:</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot @var{command} --help
</pre></div>
</div>
<p>You can also use manual pages for <strong class="command">buildbot</strong> and
<strong class="command">buildslave</strong> for quick reference on command-line options.</p>
<p>The remainder of this section describes each buildbot command. See
<a class="reference internal" href="../bb-cmdline.html" title="Command Line Index"><em>Command Line Index</em></a> for a full list.</p>
<div class="section" id="buildbot">
<h2>buildbot<a class="headerlink" href="#buildbot" title="Permalink to this headline">¶</a></h2>
<p>The <strong class="command">buildbot</strong> command-line tool can be used to start or stop a
buildmaster or buildbot, and to interact with a running buildmaster.
Some of its subcommands are intended for buildmaster admins, while
some are for developers who are editing the code that the buildbot is
monitoring.</p>
<div class="section" id="administrator-tools">
<h3>Administrator Tools<a class="headerlink" href="#administrator-tools" title="Permalink to this headline">¶</a></h3>
<p>The following <strong class="command">buildbot</strong> sub-commands are intended for
buildmaster administrators:</p>
<div class="section" id="create-master">
<span id="cmdline-create-master"></span><h4>create-master<a class="headerlink" href="#create-master" title="Permalink to this headline">¶</a></h4>
<div class="highlight-none"><div class="highlight"><pre>buildbot create-master -r {BASEDIR}
</pre></div>
</div>
<p>This creates a new directory and populates it with files that allow it to be used as a buildmaster's base directory.</p>
<p>You will usually want to use the <em class="xref std std-option">-r</em> option to create a relocatable <tt class="file docutils literal"><span class="pre">buildbot.tac</span></tt>.
This allows you to move the master directory without editing this file.</p>
</div>
<div class="section" id="start">
<span id="cmdline-start (buildbot)"></span><h4>start<a class="headerlink" href="#start" title="Permalink to this headline">¶</a></h4>
<div class="highlight-none"><div class="highlight"><pre>buildbot start [--nodaemon] {BASEDIR}
</pre></div>
</div>
<p>This starts a buildmaster which was already created in the given base directory.
The daemon is launched in the background, with events logged to a file named <tt class="file docutils literal"><span class="pre">twistd.log</span></tt>.</p>
<p>The <em class="xref std std-option">--nodaemon</em> option instructs Buildbot to skip daemonizing.
The process will start in the foreground.
It will only return to the command-line when it is stopped.</p>
</div>
<div class="section" id="restart">
<span id="cmdline-restart (buildbot)"></span><h4>restart<a class="headerlink" href="#restart" title="Permalink to this headline">¶</a></h4>
<div class="highlight-none"><div class="highlight"><pre>buildbot restart [--nodaemon] {BASEDIR}
</pre></div>
</div>
<p>Restart the buildmaster.
This is equivalent to <tt class="docutils literal"><span class="pre">stop</span></tt> followed by <tt class="docutils literal"><span class="pre">start</span></tt>
The <em class="xref std std-option">--nodaemon</em> option has the same meaning as for <tt class="docutils literal"><span class="pre">start</span></tt>.</p>
</div>
<div class="section" id="stop">
<span id="cmdline-stop (buildbot)"></span><h4>stop<a class="headerlink" href="#stop" title="Permalink to this headline">¶</a></h4>
<div class="highlight-none"><div class="highlight"><pre>buildbot stop {BASEDIR}
</pre></div>
</div>
<p>This terminates the daemon (either buildmaster or buildslave) running in the given directory.
The <em class="xref std std-option">--clean</em> option shuts down the buildmaster cleanly.</p>
</div>
<div class="section" id="sighup">
<span id="cmdline-sighup"></span><h4>sighup<a class="headerlink" href="#sighup" title="Permalink to this headline">¶</a></h4>
<div class="highlight-none"><div class="highlight"><pre>buildbot sighup {BASEDIR}
</pre></div>
</div>
<p>This sends a SIGHUP to the buildmaster running in the given directory, which causes it to re-read its <tt class="file docutils literal"><span class="pre">master.cfg</span></tt> file.</p>
</div>
</div>
<div class="section" id="developer-tools">
<h3>Developer Tools<a class="headerlink" href="#developer-tools" title="Permalink to this headline">¶</a></h3>
<p>These tools are provided for use by the developers who are working on
the code that the buildbot is monitoring.</p>
<div class="section" id="statuslog">
<span id="cmdline-statuslog"></span><h4>statuslog<a class="headerlink" href="#statuslog" title="Permalink to this headline">¶</a></h4>
<div class="highlight-none"><div class="highlight"><pre>buildbot statuslog --master {MASTERHOST}:{PORT}
</pre></div>
</div>
<p>This command starts a simple text-based status client, one which just
prints out a new line each time an event occurs on the buildmaster.</p>
<p>The <em class="xref std std-option">--master</em> option provides the location of the
<a class="reference internal" href="cfg-statustargets.html#buildbot.status.client.PBListener" title="buildbot.status.client.PBListener"><tt class="xref py py-class docutils literal"><span class="pre">buildbot.status.client.PBListener</span></tt></a> status port, used to deliver
build information to realtime status clients. The option is always in
the form of a string, with hostname and port number separated by a
colon (<tt class="samp docutils literal"><em><span class="pre">HOSTNAME</span></em><span class="pre">:</span><em><span class="pre">PORTNUM</span></em></tt>). Note that this port is <em>not</em> the
same as the slaveport (although a future version may allow the same
port number to be used for both purposes). If you get an error message
to the effect of <tt class="docutils literal"><span class="pre">Failure:</span> <span class="pre">twisted.cred.error.UnauthorizedLogin:</span></tt>,
this may indicate that you are connecting to the slaveport rather than
a <tt class="xref py py-class docutils literal"><span class="pre">PBListener</span></tt> port.</p>
<p>The <em class="xref std std-option">--master</em> option can also be provided by the
<tt class="docutils literal"><span class="pre">masterstatus</span></tt> name in <tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt>
(see <a class="reference internal" href="#buildbot-config-directory"><em>.buildbot config directory</em></a>).</p>
</div>
<div class="section" id="statusgui">
<span id="cmdline-statusgui"></span><h4>statusgui<a class="headerlink" href="#statusgui" title="Permalink to this headline">¶</a></h4>
<p>If you have set up a <a class="reference internal" href="cfg-statustargets.html#status-PBListener" title="PBListener"><tt class="xref bb bb-status docutils literal"><span class="pre">PBListener</span></tt></a>, you will be able
to monitor your Buildbot using a simple Gtk+ application invoked with
the <tt class="docutils literal"><span class="pre">buildbot</span> <span class="pre">statusgui</span></tt> command:</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot statusgui --master {MASTERHOST}:{PORT}
</pre></div>
</div>
<p>This command starts a simple Gtk+-based status client, which contains a few
boxes for each Builder that change color as events occur. It uses the same
<tt class="docutils literal"><span class="pre">--master</span></tt> argument and <tt class="docutils literal"><span class="pre">masterstatus</span></tt> option as the
<tt class="docutils literal"><span class="pre">buildbot</span> <span class="pre">statuslog</span></tt> command (<a class="reference internal" href="#cmdline-statuslog" title="statuslog"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">statuslog</span></tt></a>).</p>
</div>
<div class="section" id="try">
<span id="cmdline-try"></span><h4>try<a class="headerlink" href="#try" title="Permalink to this headline">¶</a></h4>
<p>This lets a developer to ask the question <tt class="docutils literal"><span class="pre">What</span> <span class="pre">would</span> <span class="pre">happen</span> <span class="pre">if</span> <span class="pre">I</span>
<span class="pre">committed</span> <span class="pre">this</span> <span class="pre">patch</span> <span class="pre">right</span> <span class="pre">now?</span></tt>. It runs the unit test suite (across
multiple build platforms) on the developer's current code, allowing
them to make sure they will not break the tree when they finally
commit their changes.</p>
<p>The <tt class="docutils literal"><span class="pre">buildbot</span> <span class="pre">try</span></tt> command is meant to be run from within a
developer's local tree, and starts by figuring out the base revision
of that tree (what revision was current the last time the tree was
updated), and a patch that can be applied to that revision of the tree
to make it match the developer's copy. This <tt class="docutils literal"><span class="pre">(revision,</span> <span class="pre">patch)</span></tt> pair is
then sent to the buildmaster, which runs a build with that
<tt class="xref py py-class docutils literal"><span class="pre">SourceStamp</span></tt>. If you want, the tool will emit status messages as the
builds run, and will not terminate until the first failure has been
detected (or the last success).</p>
<p>There is an alternate form which accepts a pre-made patch file
(typically the output of a command like <strong class="command">svn diff</strong>). This <tt class="docutils literal"><span class="pre">--diff</span></tt>
form does not require a local tree to run from. See <a class="reference internal" href="#try-diff"><em>try --diff</em></a> concerning
the <tt class="docutils literal"><span class="pre">--diff</span></tt> command option.</p>
<p>For this command to work, several pieces must be in place: the
<a class="reference internal" href="cfg-schedulers.html#sched-Try_Jobdir" title="Try_Jobdir"><tt class="xref bb bb-sched docutils literal"><span class="pre">Try_Jobdir</span></tt></a> or :<a class="reference internal" href="cfg-schedulers.html#sched-Try_Userpass" title="Try_Userpass"><tt class="xref bb bb-sched docutils literal"><span class="pre">Try_Userpass</span></tt></a>, as well as some client-side
configuration.</p>
<div class="section" id="locating-the-master">
<h5>Locating the master<a class="headerlink" href="#locating-the-master" title="Permalink to this headline">¶</a></h5>
<p>The <strong class="command">try</strong> command needs to be told how to connect to the
try scheduler, and must know which of the authentication
approaches described above is in use by the buildmaster. You specify
the approach by using <tt class="docutils literal"><span class="pre">--connect=ssh</span></tt> or <tt class="docutils literal"><span class="pre">--connect=pb</span></tt>
(or <tt class="docutils literal"><span class="pre">try_connect</span> <span class="pre">=</span> <span class="pre">'ssh'</span></tt> or <tt class="docutils literal"><span class="pre">try_connect</span> <span class="pre">=</span> <span class="pre">'pb'</span></tt> in
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt>).</p>
<p>For the PB approach, the command must be given a <em class="xref std std-option">--master</em>
argument (in the form <tt class="samp docutils literal"><em><span class="pre">HOST</span></em><span class="pre">:</span><em><span class="pre">PORT</span></em></tt>) that points to TCP port that you
picked in the <tt class="xref py py-class docutils literal"><span class="pre">Try_Userpass</span></tt> scheduler. It also takes a
<em class="xref std std-option">--username</em> and <em class="xref std std-option">--passwd</em> pair of arguments that match
one of the entries in the buildmaster's <tt class="docutils literal"><span class="pre">userpass</span></tt> list. These
arguments can also be provided as <tt class="docutils literal"><span class="pre">try_master</span></tt>,
<tt class="docutils literal"><span class="pre">try_username</span></tt>, and <tt class="docutils literal"><span class="pre">try_password</span></tt> entries in the
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt> file.</p>
<p>For the SSH approach, the command must be given <em class="xref std std-option">--host</em> and
<em class="xref std std-option">--username</em>, to get to the buildmaster host. It must also be given
<em class="xref std std-option">--jobdir</em>, which points to the inlet directory configured
above. The jobdir can be relative to the user's home directory, but
most of the time you will use an explicit path like
<tt class="file docutils literal"><span class="pre">~buildbot/project/trydir</span></tt>. These arguments can be provided in
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt> as <tt class="docutils literal"><span class="pre">try_host</span></tt>, <tt class="docutils literal"><span class="pre">try_username</span></tt>,
<tt class="docutils literal"><span class="pre">try_password</span></tt>, and <tt class="docutils literal"><span class="pre">try_jobdir</span></tt>.</p>
<p>The SSH approach also provides a <em class="xref std std-option">--buildbotbin</em> argument to
allow specification of the buildbot binary to run on the
buildmaster. This is useful in the case where buildbot is installed in
a <a class="reference internal" href="installation.html#installation-in-a-virtualenv"><em>virtualenv</em></a> on the buildmaster
host, or in other circumstances where the buildbot command is not on
the path of the user given by <em class="xref std std-option">--username</em>. The
<em class="xref std std-option">--buildbotbin</em> argument can be provided in
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt> as <tt class="docutils literal"><span class="pre">try_buildbotbin</span></tt></p>
<p>The following command line arguments are deprecated, but retained for
backward compatibility:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">--tryhost</span></kbd></td>
<td>is replaced by <em class="xref std std-option">--host</em></td></tr>
<tr><td class="option-group">
<kbd><span class="option">--trydir</span></kbd></td>
<td>is replaced by <em class="xref std std-option">--jobdir</em></td></tr>
<tr><td class="option-group">
<kbd><span class="option">--master</span></kbd></td>
<td>is replaced by <em class="xref std std-option">--masterstatus</em></td></tr>
</tbody>
</table>
<p>Likewise, the following <tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt> file entries are
deprecated, but retained for backward compatibility:</p>
<blockquote>
<div><ul class="simple">
<li><tt class="docutils literal"><span class="pre">try_dir</span></tt> is replaced by <tt class="docutils literal"><span class="pre">try_jobdir</span></tt></li>
<li><tt class="docutils literal"><span class="pre">masterstatus</span></tt> is replaced by <tt class="docutils literal"><span class="pre">try_masterstatus</span></tt></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="waiting-for-results">
<h5>Waiting for results<a class="headerlink" href="#waiting-for-results" title="Permalink to this headline">¶</a></h5>
<p>If you provide the <em class="xref std std-option">--wait</em> option (or <tt class="docutils literal"><span class="pre">try_wait</span> <span class="pre">=</span> <span class="pre">True</span></tt>
in <tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt>), the <tt class="docutils literal"><span class="pre">buildbot</span> <span class="pre">try</span></tt> command will
wait until your changes have either been proven good or bad before
exiting. Unless you use the <em class="xref std std-option">--quiet</em> option (or
<tt class="docutils literal"><span class="pre">try_quiet=True</span></tt>), it will emit a progress message every 60
seconds until the builds have completed.</p>
<p>The SSH connection method does not support waiting for results.</p>
</div>
<div class="section" id="choosing-the-builders">
<h5>Choosing the Builders<a class="headerlink" href="#choosing-the-builders" title="Permalink to this headline">¶</a></h5>
<p>A trial build is performed on multiple Builders at the same time, and
the developer gets to choose which Builders are used (limited to a set
selected by the buildmaster admin with the <tt class="xref py py-class docutils literal"><span class="pre">TryScheduler</span></tt>'s
<tt class="docutils literal"><span class="pre">builderNames=</span></tt> argument). The set you choose will depend upon
what your goals are: if you are concerned about cross-platform
compatibility, you should use multiple Builders, one from each
platform of interest. You might use just one builder if that platform
has libraries or other facilities that allow better test coverage than
what you can accomplish on your own machine, or faster test runs.</p>
<p>The set of Builders to use can be specified with multiple
<em class="xref std std-option">--builder</em> arguments on the command line. It can also be
specified with a single <tt class="docutils literal"><span class="pre">try_builders</span></tt> option in
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt> that uses a list of strings to specify all
the Builder names:</p>
<blockquote>
<div>try_builders = ["full-OSX", "full-win32", "full-linux"]</div></blockquote>
<p>If you are using the PB approach, you can get the names of the builders
that are configured for the try scheduler using the <tt class="docutils literal"><span class="pre">get-builder-names</span></tt>
argument:</p>
<blockquote>
<div>buildbot try --get-builder-names --connect=pb --master=... --username=... --passwd=...</div></blockquote>
</div>
<div class="section" id="specifying-the-vc-system">
<h5>Specifying the VC system<a class="headerlink" href="#specifying-the-vc-system" title="Permalink to this headline">¶</a></h5>
<p>The <strong class="command">try</strong> command also needs to know how to take the
developer's current tree and extract the (revision, patch)
source-stamp pair. Each VC system uses a different process, so you
start by telling the <strong class="command">try</strong> command which VC system you are
using, with an argument like <em class="xref std std-option">--vc=cvs</em> or <em class="xref std std-option">--vc=git</em>.
This can also be provided as <tt class="docutils literal"><span class="pre">try_vc</span></tt> in
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt>.</p>
<p>The following names are recognized: <tt class="docutils literal"><span class="pre">bzr</span></tt> <tt class="docutils literal"><span class="pre">cvs</span></tt> <tt class="docutils literal"><span class="pre">darcs</span></tt> <tt class="docutils literal"><span class="pre">hg</span></tt>
<tt class="docutils literal"><span class="pre">git</span></tt> <tt class="docutils literal"><span class="pre">mtn</span></tt> <tt class="docutils literal"><span class="pre">p4</span></tt> <tt class="docutils literal"><span class="pre">svn</span></tt></p>
</div>
<div class="section" id="finding-the-top-of-the-tree">
<h5>Finding the top of the tree<a class="headerlink" href="#finding-the-top-of-the-tree" title="Permalink to this headline">¶</a></h5>
<p>Some VC systems (notably CVS and SVN) track each directory
more-or-less independently, which means the <strong class="command">try</strong> command
needs to move up to the top of the project tree before it will be able
to construct a proper full-tree patch. To accomplish this, the
<strong class="command">try</strong> command will crawl up through the parent directories
until it finds a marker file. The default name for this marker file is
<tt class="file docutils literal"><span class="pre">.buildbot-top</span></tt>, so when you are using CVS or SVN you should
<tt class="docutils literal"><span class="pre">touch</span> <span class="pre">.buildbot-top</span></tt> from the top of your tree before running
<strong class="command">buildbot try</strong>. Alternatively, you can use a filename like
<tt class="file docutils literal"><span class="pre">ChangeLog</span></tt> or <tt class="file docutils literal"><span class="pre">README</span></tt>, since many projects put one of
these files in their top-most directory (and nowhere else). To set
this filename, use <tt class="docutils literal"><span class="pre">--topfile=ChangeLog</span></tt>, or set it in the
options file with <tt class="docutils literal"><span class="pre">try_topfile</span> <span class="pre">=</span> <span class="pre">'ChangeLog'</span></tt>.</p>
<p>You can also manually set the top of the tree with
<tt class="docutils literal"><span class="pre">--topdir=~/trees/mytree</span></tt>, or <tt class="docutils literal"><span class="pre">try_topdir</span> <span class="pre">=</span>
<span class="pre">'~/trees/mytree'</span></tt>. If you use <tt class="docutils literal"><span class="pre">try_topdir</span></tt>, in a
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt> file, you will need a separate options file
for each tree you use, so it may be more convenient to use the
<tt class="docutils literal"><span class="pre">try_topfile</span></tt> approach instead.</p>
<p>Other VC systems which work on full projects instead of individual
directories (Darcs, Mercurial, Git, Monotone) do not require
<strong class="command">try</strong> to know the top directory, so the <em class="xref std std-option">--try-topfile</em>
and <em class="xref std std-option">--try-topdir</em> arguments will be ignored.</p>
<p>If the <strong class="command">try</strong> command cannot find the top directory, it will
abort with an error message.</p>
<p>The following command line arguments are deprecated, but retained for
backward compatibility:</p>
<blockquote>
<div><ul class="simple">
<li><tt class="docutils literal"><span class="pre">--try-topdir</span></tt> is replaced by <em class="xref std std-option">--topdir</em></li>
<li><tt class="docutils literal"><span class="pre">--try-topfile</span></tt> is replaced by <em class="xref std std-option">--topfile</em></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="determining-the-branch-name">
<h5>Determining the branch name<a class="headerlink" href="#determining-the-branch-name" title="Permalink to this headline">¶</a></h5>
<p>Some VC systems record the branch information in a way that <tt class="docutils literal"><span class="pre">try</span></tt>
can locate it. For the others, if you are using something other than
the default branch, you will have to tell the buildbot which branch
your tree is using. You can do this with either the <em class="xref std std-option">--branch</em>
argument, or a <tt class="docutils literal"><span class="pre">try_branch</span></tt> entry in the
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt> file.</p>
</div>
<div class="section" id="determining-the-revision-and-patch">
<h5>Determining the revision and patch<a class="headerlink" href="#determining-the-revision-and-patch" title="Permalink to this headline">¶</a></h5>
<p>Each VC system has a separate approach for determining the tree's base
revision and computing a patch.</p>
<dl class="docutils">
<dt>CVS</dt>
<dd><strong class="command">try</strong> pretends that the tree is up to date. It converts the
current time into a <em class="xref std std-option">-D</em> time specification, uses it as the base
revision, and computes the diff between the upstream tree as of that
point in time versus the current contents. This works, more or less,
but requires that the local clock be in reasonably good sync with the
repository.</dd>
<dt>SVN</dt>
<dd><strong class="command">try</strong> does a <strong class="command">svn status -u</strong> to find the latest
repository revision number (emitted on the last line in the <tt class="samp docutils literal"><span class="pre">Status</span>
<span class="pre">against</span> <span class="pre">revision:</span> <em><span class="pre">NN</span></em></tt> message). It then performs an <tt class="samp docutils literal"><span class="pre">svn</span> <span class="pre">diff</span>
<span class="pre">-r</span><em><span class="pre">NN</span></em></tt> to find out how your tree differs from the repository version,
and sends the resulting patch to the buildmaster. If your tree is not
up to date, this will result in the <tt class="docutils literal"><span class="pre">try</span></tt> tree being created with
the latest revision, then <em>backwards</em> patches applied to bring it
<tt class="docutils literal"><span class="pre">back</span></tt> to the version you actually checked out (plus your actual
code changes), but this will still result in the correct tree being
used for the build.</dd>
<dt>bzr</dt>
<dd><strong class="command">try</strong> does a <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">revision-info</span></tt> to find the base revision,
then a <tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">diff</span> <span class="pre">-r$base..</span></tt> to obtain the patch.</dd>
<dt>Mercurial</dt>
<dd><tt class="docutils literal"><span class="pre">hg</span> <span class="pre">parents</span> <span class="pre">--template</span> <span class="pre">'{node}\n'</span></tt> emits the full revision id (as opposed to
the common 12-char truncated) which is a SHA1 hash of the current
revision's contents. This is used as the base revision.
<tt class="docutils literal"><span class="pre">hg</span> <span class="pre">diff</span></tt> then provides the patch relative to that
revision. For <strong class="command">try</strong> to work, your working directory must only
have patches that are available from the same remotely-available
repository that the build process' <tt class="docutils literal"><span class="pre">source.Mercurial</span></tt> will use.</dd>
<dt>Perforce</dt>
<dd><strong class="command">try</strong> does a <tt class="docutils literal"><span class="pre">p4</span> <span class="pre">changes</span> <span class="pre">-m1</span> <span class="pre">...</span></tt> to determine the latest
changelist and implicitly assumes that the local tree is synced to this
revision. This is followed by a <tt class="docutils literal"><span class="pre">p4</span> <span class="pre">diff</span> <span class="pre">-du</span></tt> to obtain the patch.
A p4 patch differs slightly from a normal diff. It contains full depot
paths and must be converted to paths relative to the branch top. To convert
the following restriction is imposed. The p4base (see <a class="reference internal" href="cfg-changesources.html#chsrc-P4Source" title="P4Source"><tt class="xref bb bb-chsrc docutils literal"><span class="pre">P4Source</span></tt></a>)
is assumed to be <tt class="docutils literal"><span class="pre">//depot</span></tt></dd>
<dt>Darcs</dt>
<dd><strong class="command">try</strong> does a <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">changes</span> <span class="pre">--context</span></tt> to find the list
of all patches back to and including the last tag that was made. This text
file (plus the location of a repository that contains all these
patches) is sufficient to re-create the tree. Therefore the contents
of this <tt class="docutils literal"><span class="pre">context</span></tt> file <em>are</em> the revision stamp for a
Darcs-controlled source tree. It then does a <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">diff</span> <span class="pre">-u</span></tt>
to compute the patch relative to that revision.</dd>
<dt>Git</dt>
<dd><tt class="docutils literal"><span class="pre">git</span> <span class="pre">branch</span> <span class="pre">-v</span></tt> lists all the branches available in the local
repository along with the revision ID it points to and a short summary
of the last commit. The line containing the currently checked out
branch begins with <tt class="docutils literal"><span class="pre">* </span></tt> (star and space) while all the others start
with <tt class="docutils literal"><span class="pre"> </span></tt> (two spaces). <strong class="command">try</strong> scans for this line and extracts
the branch name and revision from it. Then it generates a diff against
the base revision.</dd>
</dl>
<dl class="docutils">
<dt>Monotone</dt>
<dd><strong class="command">mtn automate get_base_revision_id</strong> emits the full revision id
which is a SHA1 hash of the current revision's contents. This is used as
the base revision.
<strong class="command">mtn diff</strong> then provides the patch relative to that
revision. For <strong class="command">try</strong> to work, your working directory must
only have patches that are available from the same
remotely-available repository that the build process'
<tt class="xref py py-class docutils literal"><span class="pre">source.Monotone</span></tt> will use.</dd>
</dl>
</div>
<div class="section" id="patch-information">
<h5>patch information<a class="headerlink" href="#patch-information" title="Permalink to this headline">¶</a></h5>
<p>You can provide the <em class="xref std std-option">--who=dev</em> to designate who is running the
try build. This will add the <tt class="docutils literal"><span class="pre">dev</span></tt> to the Reason field on the try
build's status web page. You can also set <tt class="docutils literal"><span class="pre">try_who</span> <span class="pre">=</span> <span class="pre">dev</span></tt> in the
<tt class="file docutils literal"><span class="pre">.buildbot/options</span></tt> file. Note that <em class="xref std std-option">--who=dev</em> will not
work on version 0.8.3 or earlier masters.</p>
<p>Similarly, <em class="xref std std-option">--comment=COMMENT</em> will specify the comment for the patch,
which is also displayed in the patch information. The corresponding
config-file option is <tt class="docutils literal"><span class="pre">try_comment</span></tt>.</p>
</div>
<div class="section" id="sending-properties">
<h5>Sending properties<a class="headerlink" href="#sending-properties" title="Permalink to this headline">¶</a></h5>
<p>You can set properties to send with your change using either the
<em class="xref std std-option">--property=key=value</em> option, which sets a single property,
or the <em class="xref std std-option">--properties=key1=value1,key2=value2...</em> option,
which sets multiple comma-separated properties.
Either of these can be sepcified multiple times.
Note that the <em class="xref std std-option">--properties</em> option uses commas to split on
properties, so if your property value itself contains a comma,
you'll need to use the <em class="xref std std-option">--property</em> option to set it.</p>
</div>
</div>
<div class="section" id="try-diff">
<span id="id2"></span><h4>try --diff<a class="headerlink" href="#try-diff" title="Permalink to this headline">¶</a></h4>
<p>Sometimes you might have a patch from someone else that you want to
submit to the buildbot. For example, a user may have created a patch
to fix some specific bug and sent it to you by email. You've inspected
the patch and suspect that it might do the job (and have at least
confirmed that it doesn't do anything evil). Now you want to test it
out.</p>
<p>One approach would be to check out a new local tree, apply the patch,
run your local tests, then use <tt class="docutils literal"><span class="pre">buildbot</span> <span class="pre">try</span></tt> to run the tests on
other platforms. An alternate approach is to use the <tt class="docutils literal"><span class="pre">buildbot</span>
<span class="pre">try</span> <span class="pre">--diff</span></tt> form to have the buildbot test the patch without using a
local tree.</p>
<p>This form takes a <em class="xref std std-option">--diff</em> argument which points to a file that
contains the patch you want to apply. By default this patch will be
applied to the TRUNK revision, but if you give the optional
<em class="xref std std-option">--baserev</em> argument, a tree of the given revision will be used
as a starting point instead of TRUNK.</p>
<p>You can also use <tt class="docutils literal"><span class="pre">buildbot</span> <span class="pre">try</span> <span class="pre">--diff=-</span></tt> to read the patch
from <tt class="file docutils literal"><span class="pre">stdin</span></tt>.</p>
<p>Each patch has a <tt class="docutils literal"><span class="pre">patchlevel</span></tt> associated with it. This indicates the
number of slashes (and preceding pathnames) that should be stripped
before applying the diff. This exactly corresponds to the <em class="xref std std-option">-p</em>
or <em class="xref std std-option">--strip</em> argument to the <strong class="command">patch</strong> utility. By
default <tt class="docutils literal"><span class="pre">buildbot</span> <span class="pre">try</span> <span class="pre">--diff</span></tt> uses a patchlevel of 0, but you
can override this with the <em class="xref std std-option">-p</em> argument.</p>
<p>When you use <em class="xref std std-option">--diff</em>, you do not need to use any of the other
options that relate to a local tree, specifically <em class="xref std std-option">--vc</em>,
<em class="xref std std-option">--try-topfile</em>, or <em class="xref std std-option">--try-topdir</em>. These options will
be ignored. Of course you must still specify how to get to the
buildmaster (with <em class="xref std std-option">--connect</em>, <em class="xref std std-option">--tryhost</em>, etc).</p>
</div>
</div>
<div class="section" id="other-tools">
<h3>Other Tools<a class="headerlink" href="#other-tools" title="Permalink to this headline">¶</a></h3>
<p>These tools are generally used by buildmaster administrators.</p>
<div class="section" id="sendchange">
<span id="cmdline-sendchange"></span><h4>sendchange<a class="headerlink" href="#sendchange" title="Permalink to this headline">¶</a></h4>
<p>This command is used to tell the buildmaster about source changes. It
is intended to be used from within a commit script, installed on the
VC server. It requires that you have a <tt class="xref py py-class docutils literal"><span class="pre">PBChangeSource</span></tt>
(<a class="reference internal" href="cfg-changesources.html#chsrc-PBChangeSource" title="PBChangeSource"><tt class="xref bb bb-chsrc docutils literal"><span class="pre">PBChangeSource</span></tt></a>) running in the buildmaster (by being set in
<tt class="docutils literal"><span class="pre">c['change_source']</span></tt>).</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot sendchange --master {MASTERHOST}:{PORT} --auth {USER}:{PASS}
--who {USER} {FILENAMES..}
</pre></div>
</div>
<p>The <em class="xref std std-option">auth</em> option specifies the credentials to use to connect to the
master, in the form <tt class="docutils literal"><span class="pre">user:pass</span></tt>. If the password is omitted, then
sendchange will prompt for it. If both are omitted, the old default (username
"change" and password "changepw") will be used. Note that this password is
well-known, and should not be used on an internet-accessible port.</p>
<p>The <em class="xref std std-option">master</em> and <em class="xref std std-option">username</em> arguments can also be given in the
options file (see <a class="reference internal" href="#buildbot-config-directory"><em>.buildbot config directory</em></a>). There are other (optional)
arguments which can influence the <tt class="docutils literal"><span class="pre">Change</span></tt> that gets submitted:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">--branch</span></kbd></td>
<td>(or option <tt class="docutils literal"><span class="pre">branch</span></tt>) This provides the (string) branch specifier. If
omitted, it defaults to <tt class="docutils literal"><span class="pre">None</span></tt>, indicating the <tt class="docutils literal"><span class="pre">default</span> <span class="pre">branch</span></tt>. All files
included in this Change must be on the same branch.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--category</span></kbd></td>
<td>(or option <tt class="docutils literal"><span class="pre">category</span></tt>) This provides the (string) category specifier. If
omitted, it defaults to <tt class="docutils literal"><span class="pre">None</span></tt>, indicating <tt class="docutils literal"><span class="pre">no</span> <span class="pre">category</span></tt>. The category property
can be used by <tt class="xref py py-class docutils literal"><span class="pre">Scheduler</span></tt>s to filter what changes they listen to.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--project</span></kbd></td>
<td>(or option <tt class="docutils literal"><span class="pre">project</span></tt>) This provides the (string) project to which this
change applies, and defaults to ''. The project can be used by schedulers to
decide which builders should respond to a particular change.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--repository</span></kbd></td>
<td>(or option <tt class="docutils literal"><span class="pre">repository</span></tt>) This provides the repository from which this
change came, and defaults to <tt class="docutils literal"><span class="pre">''</span></tt>.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--revision</span></kbd></td>
<td>This provides a revision specifier, appropriate to the VC system in use.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--revision_file</span></kbd></td>
</tr>
<tr><td> </td><td>This provides a filename which will be opened and the contents used as
the revision specifier. This is specifically for Darcs, which uses the
output of <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">changes</span> <span class="pre">--context</span></tt> as a revision specifier.
This context file can be a couple of kilobytes long, spanning a couple
lines per patch, and would be a hassle to pass as a command-line
argument.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--property</span></kbd></td>
<td>This parameter is used to set a property on the <tt class="xref py py-class docutils literal"><span class="pre">Change</span></tt> generated by <tt class="docutils literal"><span class="pre">sendchange</span></tt>.
Properties are specified as a <tt class="samp docutils literal"><em><span class="pre">name</span></em><span class="pre">:</span><em><span class="pre">value</span></em></tt> pair, separated by a colon. You may
specify many properties by passing this parameter multiple times.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--comments</span></kbd></td>
<td>This provides the change comments as a single argument. You may want
to use <em class="xref std std-option">--logfile</em> instead.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--logfile</span></kbd></td>
<td>This instructs the tool to read the change comments from the given
file. If you use <tt class="docutils literal"><span class="pre">-</span></tt> as the filename, the tool will read the
change comments from stdin.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--encoding</span></kbd></td>
<td>Specifies the character encoding for all other parameters,
defaulting to <tt class="docutils literal"><span class="pre">'utf8'</span></tt>.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--vc</span></kbd></td>
<td>Specifies which VC system the Change is coming from, one of: <tt class="docutils literal"><span class="pre">cvs</span></tt>,
<tt class="docutils literal"><span class="pre">svn</span></tt>, <tt class="docutils literal"><span class="pre">darcs</span></tt>, <tt class="docutils literal"><span class="pre">hg</span></tt>, <tt class="docutils literal"><span class="pre">bzr</span></tt>, <tt class="docutils literal"><span class="pre">git</span></tt>, <tt class="docutils literal"><span class="pre">mtn</span></tt>, or <tt class="docutils literal"><span class="pre">p4</span></tt>.
Defaults to <tt class="docutils literal"><span class="pre">None</span></tt>.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="debugclient">
<span id="cmdline-debugclient"></span><h4>debugclient<a class="headerlink" href="#debugclient" title="Permalink to this headline">¶</a></h4>
<div class="highlight-none"><div class="highlight"><pre>buildbot debugclient --master {MASTERHOST}:{PORT} --passwd {DEBUGPW}
</pre></div>
</div>
<p>This launches a small Gtk+/Glade-based debug tool, connecting to the
buildmaster's <tt class="docutils literal"><span class="pre">debug</span> <span class="pre">port</span></tt>. This debug port shares the same port
number as the slaveport (see <a class="reference internal" href="cfg-global.html#setting-the-pb-port-for-slaves"><em>Setting the PB Port for Slaves</em></a>), but the
<tt class="docutils literal"><span class="pre">debugPort</span></tt> is only enabled if you set a debug password in the
buildmaster's config file (see <a class="reference internal" href="cfg-global.html#debug-options"><em>Debug Options</em></a>). The
<em class="xref std std-option">--passwd</em> option must match the <tt class="docutils literal"><span class="pre">c['debugPassword']</span></tt>
value.</p>
<p><em class="xref std std-option">--master</em> can also be provided in <tt class="file docutils literal"><span class="pre">.debug/options</span></tt> by the
<tt class="docutils literal"><span class="pre">master</span></tt> key. <em class="xref std std-option">--passwd</em> can be provided by the
<tt class="docutils literal"><span class="pre">debugPassword</span></tt> key. See <a class="reference internal" href="#buildbot-config-directory"><em>.buildbot config directory</em></a>.</p>
<p>The <em class="guilabel">Connect</em> button must be pressed before any of the other
buttons will be active. This establishes the connection to the
buildmaster. The other sections of the tool are as follows:</p>
<dl class="docutils">
<dt><em class="guilabel">Reload .cfg</em></dt>
<dd>Forces the buildmaster to reload its <tt class="file docutils literal"><span class="pre">master.cfg</span></tt> file. This is
equivalent to sending a SIGHUP to the buildmaster, but can be done
remotely through the debug port. Note that it is a good idea to be
watching the buildmaster's <tt class="file docutils literal"><span class="pre">twistd.log</span></tt> as you reload the config
file, as any errors which are detected in the config file will be
announced there.</dd>
<dt><em class="guilabel">Rebuild .py</em></dt>
<dd>(not yet implemented). The idea here is to use Twisted's <tt class="docutils literal"><span class="pre">rebuild</span></tt>
facilities to replace the buildmaster's running code with a new
version. Even if this worked, it would only be used by buildbot
developers.</dd>
<dt><em class="guilabel">poke IRC</em></dt>
<dd>This locates a <tt class="xref py py-class docutils literal"><span class="pre">words.IRC</span></tt> status target and causes it to emit a
message on all the channels to which it is currently connected. This
was used to debug a problem in which the buildmaster lost the
connection to the IRC server and did not attempt to reconnect.</dd>
<dt><em class="guilabel">Commit</em></dt>
<dd>This allows you to inject a <tt class="xref py py-class docutils literal"><span class="pre">Change</span></tt>, just as if a real one had been
delivered by whatever VC hook you are using. You can set the name of
the committed file and the name of the user who is doing the commit.
Optionally, you can also set a revision for the change. If the
revision you provide looks like a number, it will be sent as an
integer, otherwise it will be sent as a string.</dd>
<dt><em class="guilabel">Force Build</em></dt>
<dd>This lets you force a <tt class="xref py py-class docutils literal"><span class="pre">Builder</span></tt> (selected by name) to start a build of
the current source tree.</dd>
<dt><em class="guilabel">Currently</em></dt>
<dd>(obsolete). This was used to manually set the status of the given
<tt class="xref py py-class docutils literal"><span class="pre">Builder</span></tt>, but the status-assignment code was changed in an incompatible
way and these buttons are no longer meaningful.</dd>
</dl>
</div>
<div class="section" id="user">
<span id="cmdline-user"></span><h4>user<a class="headerlink" href="#user" title="Permalink to this headline">¶</a></h4>
<p>Note that in order to use this command, you need to configure a
<cite>CommandlineUserManager</cite> instance in your <cite>master.cfg</cite> file, which is
explained in <a class="reference internal" href="cfg-global.html#users-options"><em>Users Options</em></a>.</p>
<p>This command allows you to manage users in buildbot's database.
No extra requirements are needed to use this command, aside from
the Buildmaster running. For details on how Buildbot manages users,
see <a class="reference internal" href="concepts.html#concepts-users"><em>Users</em></a>.</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">--master</span></kbd></td>
<td>The <strong class="command">user</strong> command can be run virtually anywhere
provided a location of the running buildmaster. The <em class="xref std std-option">master</em>
argument is of the form <tt class="docutils literal"><span class="pre">{MASTERHOST}:{PORT}</span></tt>.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--username</span></kbd></td>
<td>PB connection authentication that should match the arguments to
<cite>CommandlineUserManager</cite>.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--passwd</span></kbd></td>
<td>PB connection authentication that should match the arguments to
<cite>CommandlineUserManager</cite>.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--op</span></kbd></td>
<td>There are four supported values for the <em class="xref std std-option">op</em> argument:
<em class="xref std std-option">add</em>, <em class="xref std std-option">update</em>, <em class="xref std std-option">remove</em>, and
<em class="xref std std-option">get</em>. Each are described in full in the following sections.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--bb_username</span></kbd></td>
<td>Used with the <em class="xref std std-option">update</em> option, this sets the user's username
for web authentication in the database. It requires <em class="xref std std-option">bb_password</em>
to be set along with it.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--bb_password</span></kbd></td>
<td>Also used with the <em class="xref std std-option">update</em> option, this sets the password
portion of a user's web authentication credentials into the database.
The password is first encrypted prior to storage for security reasons.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--ids</span></kbd></td>
<td><p class="first">When working with users, you need to be able to refer to them by
unique identifiers to find particular users in the database. The
<em class="xref std std-option">ids</em> option lets you specify a comma separated list of these
identifiers for use with the <strong class="command">user</strong> command.</p>
<p class="last">The <em class="xref std std-option">ids</em> option is used only when using <em class="xref std std-option">remove</em>
or <em class="xref std std-option">show</em>.</p>
</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--info</span></kbd></td>
<td><p class="first">Users are known in buildbot as a collection of attributes tied
together by some unique identifier (see <a class="reference internal" href="concepts.html#concepts-users"><em>Users</em></a>). These
attributes are specified in the form <tt class="docutils literal"><span class="pre">{TYPE}={VALUE}</span></tt> when
using the <em class="xref std std-option">info</em> option. These <tt class="docutils literal"><span class="pre">{TYPE}={VALUE}</span></tt> pairs
are specified in a comma separated list, so for example:</p>
<div class="highlight-none"><div class="highlight"><pre>--info=svn=jschmo,git='Joe Schmo <joe@schmo.com>'
</pre></div>
</div>
<p>The <em class="xref std std-option">info</em> option can be specified multiple times in the
<strong class="command">user</strong> command, as each specified option will be interpreted
as a new user. Note that <em class="xref std std-option">info</em> is only used with <em class="xref std std-option">add</em>
or with <em class="xref std std-option">update</em>, and whenever you use <em class="xref std std-option">update</em> you need
to specify the identifier of the user you want to update. This is done
by prepending the <em class="xref std std-option">info</em> arguments with <tt class="docutils literal"><span class="pre">{ID:}</span></tt>. If we were
to update <tt class="docutils literal"><span class="pre">'jschmo'</span></tt> from the previous example, it would look like this:</p>
<div class="last highlight-none"><div class="highlight"><pre>--info=jschmo:git='Joseph Schmo <joe@schmo.com>'
</pre></div>
</div>
</td></tr>
</tbody>
</table>
<p>Note that <em class="xref std std-option">--master</em>, <em class="xref std std-option">--username</em>, <em class="xref std std-option">--passwd</em>, and
<em class="xref std std-option">--op</em> are always required to issue the <strong class="command">user</strong> command.</p>
<p>The <em class="xref std std-option">--master</em>, <em class="xref std std-option">--username</em>, and <em class="xref std std-option">--passwd</em> options
can be specified in the option file with keywords <em class="xref std std-option">user_master</em>,
<em class="xref std std-option">user_username</em>, and <em class="xref std std-option">user_passwd</em>, respectively. If
<em class="xref std std-option">user_master</em> is not specified, then <em class="xref std std-option">master</em> from the options
file will be used instead.</p>
<p>Below are examples of how each command should look. Whenever a
<strong class="command">user</strong> command is successful, results will be shown
to whoever issued the command.</p>
<p>For <em class="xref std std-option">add</em>:</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot user --master={MASTERHOST} --op=add \
--username={USER} --passwd={USERPW} \
--info={TYPE}={VALUE},...
</pre></div>
</div>
<p>For <em class="xref std std-option">update</em>:</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot user --master={MASTERHOST} --op=update \
--username={USER} --passwd={USERPW} \
--info={ID}:{TYPE}={VALUE},...
</pre></div>
</div>
<p>For <em class="xref std std-option">remove</em>:</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot user --master={MASTERHOST} --op=remove \
--username={USER} --passwd={USERPW} \
--ids={ID1},{ID2},...
</pre></div>
</div>
<p>For <em class="xref std std-option">get</em>:</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot user --master={MASTERHOST} --op=get \
--username={USER} --passwd={USERPW} \
--ids={ID1},{ID2},...
</pre></div>
</div>
<p>A note on <em class="xref std std-option">update</em>: when updating the <em class="xref std std-option">bb_username</em>
and <em class="xref std std-option">bb_password</em>, the <em class="xref std std-option">info</em> doesn't need to have
additional <tt class="docutils literal"><span class="pre">{TYPE}={VALUE}</span></tt> pairs to update and can just take
the <tt class="docutils literal"><span class="pre">{ID}</span></tt> portion.</p>
</div>
</div>
<div class="section" id="buildbot-config-directory">
<span id="id3"></span><h3>.buildbot config directory<a class="headerlink" href="#buildbot-config-directory" title="Permalink to this headline">¶</a></h3>
<p>Many of the <strong class="command">buildbot</strong> tools must be told how to contact the
buildmaster that they interact with. This specification can be
provided as a command-line argument, but most of the time it will be
easier to set them in an <tt class="docutils literal"><span class="pre">options</span></tt> file. The <strong class="command">buildbot</strong>
command will look for a special directory named <tt class="file docutils literal"><span class="pre">.buildbot</span></tt>,
starting from the current directory (where the command was run) and
crawling upwards, eventually looking in the user's home directory. It
will look for a file named <tt class="file docutils literal"><span class="pre">options</span></tt> in this directory, and will
evaluate it as a Python script, looking for certain names to be set.
You can just put simple <tt class="docutils literal"><span class="pre">name</span> <span class="pre">=</span> <span class="pre">'value'</span></tt> pairs in this file to
set the options.</p>
<p>For a description of the names used in this file, please see the
documentation for the individual <strong class="command">buildbot</strong> sub-commands. The
following is a brief sample of what this file's contents could be.</p>
<div class="highlight-none"><div class="highlight"><pre># for status-reading tools
masterstatus = 'buildbot.example.org:12345'
# for 'sendchange' or the debug port
master = 'buildbot.example.org:18990'
debugPassword = 'eiv7Po'
</pre></div>
</div>
<p>Note carefully that the names in the <tt class="file docutils literal"><span class="pre">options</span></tt> file usually do not match
the command-line option name.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">masterstatus</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--master</em> for <a class="reference internal" href="#cmdline-statuslog" title="statuslog"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">statuslog</span></tt></a> and <a class="reference internal" href="#cmdline-statusgui" title="statusgui"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">statusgui</span></tt></a>, this
gives the location of the <tt class="xref py py-class docutils literal"><span class="pre">client.PBListener</span></tt> status port.</dd>
<dt><tt class="docutils literal"><span class="pre">master</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--master</em> for <a class="reference internal" href="#cmdline-debugclient" title="debugclient"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">debugclient</span></tt></a> and <a class="reference internal" href="#cmdline-sendchange" title="sendchange"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">sendchange</span></tt></a>.
This option is used for two purposes. It is the location of the
<tt class="docutils literal"><span class="pre">debugPort</span></tt> for <tt class="docutils literal"><span class="pre">debugclient</span></tt> and the location of the
<tt class="xref py py-class docutils literal"><span class="pre">pb.PBChangeSource</span></tt> for <tt class="docutils literal"><span class="pre">`sendchange</span></tt>. Generally these are the
same port.</dd>
<dt><tt class="docutils literal"><span class="pre">debugPassword</span></tt></dt>
<dd><p class="first">Equivalent to <em class="xref std std-option">--passwd</em> for <a class="reference internal" href="#cmdline-debugclient" title="debugclient"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">debugclient</span></tt></a>.</p>
<div class="last admonition important">
<p class="first admonition-title">Important</p>
<p class="last">This value must match the value of <a class="reference internal" href="cfg-global.html#cfg-debugPassword" title="debugPassword"><tt class="xref bb bb-cfg docutils literal"><span class="pre">debugPassword</span></tt></a>, used to
protect the debug port, for the <a class="reference internal" href="#cmdline-debugclient" title="debugclient"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">debugclient</span></tt></a> command.</p>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">username</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--username</em> for the <a class="reference internal" href="#cmdline-sendchange" title="sendchange"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">sendchange</span></tt></a> command.</dd>
<dt><tt class="docutils literal"><span class="pre">branch</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--branch</em> for the <a class="reference internal" href="#cmdline-sendchange" title="sendchange"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">sendchange</span></tt></a> command.</dd>
<dt><tt class="docutils literal"><span class="pre">category</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--category</em> for the <a class="reference internal" href="#cmdline-sendchange" title="sendchange"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">sendchange</span></tt></a> command.</dd>
<dt><tt class="docutils literal"><span class="pre">try_connect</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--connect</em>, this specifies how the <a class="reference internal" href="#cmdline-try" title="try"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">try</span></tt></a> command should
deliver its request to the buildmaster. The currently accepted values are
<tt class="docutils literal"><span class="pre">ssh</span></tt> and <tt class="docutils literal"><span class="pre">pb</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">try_builders</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--builders</em>, specifies which builders should be used for
the <a class="reference internal" href="#cmdline-try" title="try"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">try</span></tt></a> build.</dd>
<dt><tt class="docutils literal"><span class="pre">try_vc</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--vc</em> for <a class="reference internal" href="#cmdline-try" title="try"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">try</span></tt></a>, this specifies the version control
system being used.</dd>
<dt><tt class="docutils literal"><span class="pre">try_branch</span></tt></dt>
<dd>Equivalent to <em class="xref std std-option">--branch</em>, this indicates that the current tree is on a
non-trunk branch.</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">try_topdir</span></tt></p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">try_topfile</span></tt></dt>
<dd>Use <tt class="docutils literal"><span class="pre">try_topdir</span></tt>, equivalent to <em class="xref std std-option">--try-topdir</em>, to explicitly
indicate the top of your working tree, or <tt class="docutils literal"><span class="pre">try_topfile</span></tt>, equivalent to
<em class="xref std std-option">--try-topfile</em> to name a file that will only be found in that top-most
directory.</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">try_host</span></tt></p>
<p><tt class="docutils literal"><span class="pre">try_username</span></tt></p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">try_dir</span></tt></dt>
<dd>When <tt class="docutils literal"><span class="pre">try_connect</span></tt> is <tt class="docutils literal"><span class="pre">ssh</span></tt>, the command will use <tt class="docutils literal"><span class="pre">try_host</span></tt> for
<em class="xref std std-option">--tryhost</em>, <tt class="docutils literal"><span class="pre">try_username</span></tt> for <em class="xref std std-option">--username</em>, and <tt class="docutils literal"><span class="pre">try_dir</span></tt>
for <em class="xref std std-option">--trydir</em>. Apologies for the confusing presence and absence of
'try'.</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">try_username</span></tt></p>
<p><tt class="docutils literal"><span class="pre">try_password</span></tt></p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">try_master</span></tt></dt>
<dd>Similarly, when <tt class="docutils literal"><span class="pre">try_connect</span></tt> is <tt class="docutils literal"><span class="pre">pb</span></tt>, the command will pay attention to
<tt class="docutils literal"><span class="pre">try_username</span></tt> for <em class="xref std std-option">--username</em>, <tt class="docutils literal"><span class="pre">try_password</span></tt> for
<em class="xref std std-option">--passwd</em>, and <tt class="docutils literal"><span class="pre">try_master</span></tt> for <em class="xref std std-option">--master</em>.</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">try_wait</span></tt></p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">masterstatus</span></tt></dt>
<dd><tt class="docutils literal"><span class="pre">try_wait</span></tt> and <tt class="docutils literal"><span class="pre">masterstatus</span></tt> (equivalent to <em class="xref std std-option">--wait</em> and
<tt class="docutils literal"><span class="pre">master</span></tt>, respectively) are used to ask the <a class="reference internal" href="#cmdline-try" title="try"><tt class="xref bb bb-cmdline docutils literal"><span class="pre">try</span></tt></a> command to wait for
the requested build to complete.</dd>
</dl>
</div>
</div>
<div class="section" id="buildslave">
<h2>buildslave<a class="headerlink" href="#buildslave" title="Permalink to this headline">¶</a></h2>
<p><strong class="command">buildslave</strong> command-line tool is used for buildslave management
only and does not provide any additional functionality. One can create,
start, stop and restart the buildslave.</p>
<div class="section" id="create-slave">
<span id="cmdline-create-slave"></span><h3>create-slave<a class="headerlink" href="#create-slave" title="Permalink to this headline">¶</a></h3>
<p>This creates a new directory and populates it with files that let it
be used as a buildslave's base directory. You must provide several
arguments, which are used to create the initial <tt class="file docutils literal"><span class="pre">buildbot.tac</span></tt>
file.</p>
<p>The <em class="xref std std-option">-r</em> option is advisable here, just like for <tt class="docutils literal"><span class="pre">create-master</span></tt>.</p>
<div class="highlight-none"><div class="highlight"><pre>buildslave create-slave -r {BASEDIR} {MASTERHOST}:{PORT} {SLAVENAME} {PASSWORD}
</pre></div>
</div>
<p>The create-slave options are described in <a class="reference internal" href="installation.html#buildslave-options"><em>Buildslave Options</em></a>.</p>
</div>
<div class="section" id="cmdline-start (buildslave)">
<span id="id4"></span><h3>start<a class="headerlink" href="#cmdline-start (buildslave)" title="Permalink to this headline">¶</a></h3>
<p>This starts a buildslave which was already created in the given base
directory. The daemon is launched in the background, with events logged
to a file named <tt class="file docutils literal"><span class="pre">twistd.log</span></tt>.</p>
<div class="highlight-none"><div class="highlight"><pre>buildslave start [--nodaemon] BASEDIR
</pre></div>
</div>
<p>The <em class="xref std std-option">--nodaemon</em> option instructs Buildbot to skip daemonizing. The
process will start in the foreground. It will only return to the command-line
when it is stopped.</p>
</div>
<div class="section" id="cmdline-restart (buildslave)">
<span id="id5"></span><h3>restart<a class="headerlink" href="#cmdline-restart (buildslave)" title="Permalink to this headline">¶</a></h3>
<div class="highlight-none"><div class="highlight"><pre>buildslave restart [--nodaemon] BASEDIR
</pre></div>
</div>
<p>This restarts a buildslave which is already running.
It is equivalent to a <tt class="docutils literal"><span class="pre">stop</span></tt> followed by a <tt class="docutils literal"><span class="pre">start</span></tt>.</p>
<p>The <em class="xref std std-option">--nodaemon</em> option has the same meaning as for <tt class="docutils literal"><span class="pre">start</span></tt>.</p>
</div>
<div class="section" id="cmdline-stop (buildslave)">
<span id="id6"></span><h3>stop<a class="headerlink" href="#cmdline-stop (buildslave)" title="Permalink to this headline">¶</a></h3>
<p>This terminates the daemon buildslave running in the given directory.</p>
<div class="highlight-none"><div class="highlight"><pre>buildbot stop BASEDIR
</pre></div>
</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 current"><a class="reference internal" href="index.html">Buildbot Manual</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html">Concepts</a></li>
<li class="toctree-l2"><a class="reference internal" href="configuration.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="customization.html">Customization</a></li>
<li class="toctree-l2"><a class="reference internal" href="new-style-steps.html">New-Style Build Steps</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="">Command-line Tool</a><ul class="simple">
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="resources.html">Resources</a></li>
<li class="toctree-l2"><a class="reference internal" href="optimization.html">Optimization</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../developer/index.html">Buildbot Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes/index.html">Release Notes for Buildbot 0.8.9</a></li>
</ul>
<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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<a href="new-style-steps.html" title="New-Style Build Steps"
>previous</a> |
<a href="resources.html" title="Resources"
>next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
>index</a>
<br/>
<a href="../_sources/manual/cmdline.txt"
rel="nofollow">Show Source</a>
</div>
<div class="right">
<div class="footer">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
