[Buildbot-commits] site manual-CVS.html,1.1,1.2

Brian Warner warner at users.sourceforge.net
Thu Aug 11 19:48:53 UTC 2005


Update of /cvsroot/buildbot/site
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22645

Modified Files:
	manual-CVS.html 
Log Message:
update

Index: manual-CVS.html
===================================================================
RCS file: /cvsroot/buildbot/site/manual-CVS.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- manual-CVS.html	20 Jul 2005 07:22:20 -0000	1.1
+++ manual-CVS.html	11 Aug 2005 19:48:49 -0000	1.2
@@ -150,7 +150,23 @@
 <li><a href="#PBListener">7.0.3 PBListener</a>
 </li></ul>
 </li></ul>
-<li><a name="toc_Resources" href="#Resources">8 Resources</a>
+<li><a name="toc_Command_002dline-tool" href="#Command_002dline-tool">8 Command-line tool</a>
+<ul>
+<li><a href="#Administrator-Tools">8.1 Administrator Tools</a>
+<li><a href="#Developer-Tools">8.2 Developer Tools</a>
+<ul>
+<li><a href="#statuslog">8.2.1 statuslog</a>
+<li><a href="#statusgui">8.2.2 statusgui</a>
+<li><a href="#try">8.2.3 try</a>
+</li></ul>
+<li><a href="#Other-Tools">8.3 Other Tools</a>
+<ul>
+<li><a href="#sendchange">8.3.1 sendchange</a>
+<li><a href="#debugclient">8.3.2 debugclient</a>
+</li></ul>
+<li><a href="#_002ebuildbot-config-directory">8.4 .buildbot config directory</a>
+</li></ul>
+<li><a name="toc_Resources" href="#Resources">9 Resources</a>
 <li><a name="toc_Developer_0027s-Appendix" href="#Developer_0027s-Appendix">Developer's Appendix</a>
 <li><a name="toc_Index" href="#Index">Index</a>
 </li></ul>
@@ -185,8 +201,9 @@
 <li><a accesskey="5" href="#Getting-Source-Code-Changes">Getting Source Code Changes</a>:   Discovering when to run a build. 
 <li><a accesskey="6" href="#Build-Process">Build Process</a>:                Controlling how each build is run. 
 <li><a accesskey="7" href="#Status-Delivery">Status Delivery</a>:              Telling the world about the build's results. 
-<li><a accesskey="8" href="#Resources">Resources</a>:                    Getting help. 
-<li><a accesskey="9" href="#Developer_0027s-Appendix">Developer's Appendix</a>
+<li><a accesskey="8" href="#Command_002dline-tool">Command-line tool</a>
+<li><a accesskey="9" href="#Resources">Resources</a>:                    Getting help. 
+<li><a href="#Developer_0027s-Appendix">Developer's Appendix</a>
 <li><a href="#Index">Index</a>:                        Complete index.
 
 </li></ul>
@@ -372,6 +389,33 @@
 <li><a href="#IRC-Bot">IRC Bot</a>
 <li><a href="#PBListener">PBListener</a>
 
+</li></ul>
+<p>Command-line tool
+
+</p>
+<ul class="menu">
+<li><a href="#Administrator-Tools">Administrator Tools</a>
+<li><a href="#Developer-Tools">Developer Tools</a>
+<li><a href="#Other-Tools">Other Tools</a>
+<li><a href="#_002ebuildbot-config-directory">.buildbot config directory</a>
+
+</li></ul>
+<p>Developer Tools
+
+</p>
+<ul class="menu">
+<li><a href="#statuslog">statuslog</a>
+<li><a href="#statusgui">statusgui</a>
+<li><a href="#try">try</a>
+
+</li></ul>
+<p>Other Tools
+
+</p>
+<ul class="menu">
+<li><a href="#sendchange">sendchange</a>
+<li><a href="#debugclient">debugclient</a>
+
    </ul>
 
 <div class="node">
@@ -3728,7 +3772,7 @@
 </pre>
    <div class="node">
 <p><hr>
-<a name="Status-Delivery"></a>Next: <a rel="next" accesskey="n" href="#Resources">Resources</a>,
+<a name="Status-Delivery"></a>Next: <a rel="next" accesskey="n" href="#Command_002dline-tool">Command-line tool</a>,
 Previous: <a rel="previous" accesskey="p" href="#Build-Process">Build Process</a>,
 Up: <a rel="up" accesskey="u" href="#Top">Top</a>
 <br>
@@ -3873,13 +3917,584 @@
 
 <div class="node">
 <p><hr>
-<a name="Resources"></a>Next: <a rel="next" accesskey="n" href="#Developer_0027s-Appendix">Developer's Appendix</a>,
+<a name="Command_002dline-tool"></a>Next: <a rel="next" accesskey="n" href="#Resources">Resources</a>,
 Previous: <a rel="previous" accesskey="p" href="#Status-Delivery">Status Delivery</a>,
 Up: <a rel="up" accesskey="u" href="#Top">Top</a>
 <br>
 </div>
 
-<h2 class="chapter">8 Resources</h2>
+<h2 class="chapter">8 Command-line tool</h2>
+
+<p>The <span class="command">buildbot</span> 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.
+
+<ul class="menu">
+<li><a accesskey="1" href="#Administrator-Tools">Administrator Tools</a>
+<li><a accesskey="2" href="#Developer-Tools">Developer Tools</a>
+<li><a accesskey="3" href="#Other-Tools">Other Tools</a>
+<li><a accesskey="4" href="#_002ebuildbot-config-directory">.buildbot config directory</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="Administrator-Tools"></a>Next: <a rel="next" accesskey="n" href="#Developer-Tools">Developer Tools</a>,
+Previous: <a rel="previous" accesskey="p" href="#Command_002dline-tool">Command-line tool</a>,
+Up: <a rel="up" accesskey="u" href="#Command_002dline-tool">Command-line tool</a>
+<br>
+</div>
+
+<h3 class="section">8.1 Administrator Tools</h3>
+
+<p>The following <span class="command">buildbot</span> sub-commands are intended for
+buildmaster administrators:
+
+<h3 class="heading">master</h3>
+
+<p>This creates a new directory and populates it with files that allow it
+to be used as a buildmaster's base directory.
+
+<pre class="example">     buildbot master BASEDIR
+</pre>
+   <h3 class="heading">slave</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 <span class="file">buildbot.tac</span>
+file.
+
+<pre class="example">     buildbot slave <var>BASEDIR</var> <var>MASTERHOST</var>:<var>PORT</var> <var>SLAVENAME</var> <var>PASSWORD</var>
+</pre>
+   <h3 class="heading">start</h3>
+
+<p>This starts a buildmaster or buildslave which was already created in
+the given base directory. The daemon is launched in the background,
+with events logged to a file named <span class="file">twistd.log</span>.
+
+<pre class="example">     buildbot start BASEDIR
+</pre>
+   <h3 class="heading">stop</h3>
+
+<p>This terminates the daemon (either buildmaster or buildslave) running
+in the given directory.
+
+<pre class="example">     buildbot stop BASEDIR
+</pre>
+   <h3 class="heading">sighup</h3>
+
+<p>This sends a SIGHUP to the buildmaster running in the given directory,
+which causes it to re-read its <span class="file">master.cfg</span> file.
+
+<pre class="example">     buildbot sighup BASEDIR
+</pre>
+   <div class="node">
+<p><hr>
+<a name="Developer-Tools"></a>Next: <a rel="next" accesskey="n" href="#Other-Tools">Other Tools</a>,
+Previous: <a rel="previous" accesskey="p" href="#Administrator-Tools">Administrator Tools</a>,
+Up: <a rel="up" accesskey="u" href="#Command_002dline-tool">Command-line tool</a>
+<br>
+</div>
+
+<h3 class="section">8.2 Developer Tools</h3>
+
+<p>These tools are provided for use by the developers who are working on
+the code that the buildbot is monitoring.
+
+<ul class="menu">
+<li><a accesskey="1" href="#statuslog">statuslog</a>
+<li><a accesskey="2" href="#statusgui">statusgui</a>
+<li><a accesskey="3" href="#try">try</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="statuslog"></a>Next: <a rel="next" accesskey="n" href="#statusgui">statusgui</a>,
+Previous: <a rel="previous" accesskey="p" href="#Developer-Tools">Developer Tools</a>,
+Up: <a rel="up" accesskey="u" href="#Developer-Tools">Developer Tools</a>
+<br>
+</div>
+
+<h4 class="subsection">8.2.1 statuslog</h4>
+
+<pre class="example">     buildbot statuslog --master <var>MASTERHOST</var>:<var>PORT</var>
+</pre>
+   <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>The <span class="option">--master</span> option provides the location of the
+<code>client.PBListener</code> 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
+(<code>HOSTNAME:PORTNUM</code>). 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).
+
+   <p>The <span class="option">--master</span> option can also be provided by the
+<code>masterstatus</code> name in <span class="file">.buildbot/options</span> (see <a href="#_002ebuildbot-config-directory">.buildbot config directory</a>).
+
+<div class="node">
+<p><hr>
+<a name="statusgui"></a>Next: <a rel="next" accesskey="n" href="#try">try</a>,
+Previous: <a rel="previous" accesskey="p" href="#statuslog">statuslog</a>,
+Up: <a rel="up" accesskey="u" href="#Developer-Tools">Developer Tools</a>
+<br>
+</div>
+
+<h4 class="subsection">8.2.2 statusgui</h4>
+
+<pre class="example">     buildbot statusgui --master <var>MASTERHOST</var>:<var>PORT</var>
+</pre>
+   <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 <span class="option">--master</span> argument as the <span class="command">buildbot
+statuslog</span> command (see <a href="#statuslog">statuslog</a>).
+
+<div class="node">
+<p><hr>
+<a name="try"></a>Previous: <a rel="previous" accesskey="p" href="#statusgui">statusgui</a>,
+Up: <a rel="up" accesskey="u" href="#Developer-Tools">Developer Tools</a>
+<br>
+</div>
+
+<h4 class="subsection">8.2.3 try</h4>
+
+<p>This lets a developer to ask the question “What would happen if I
+committed this patch right now?”. 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>The <span class="command">buildbot try</span> 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 (revision, patch) pair is
+then sent to the buildmaster, which runs a build with that
+SourceStamp. By default, 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>For this command to work, several pieces must be in place:
+
+<h3 class="heading">TryScheduler</h3>
+
+<p>The buildmaster must have a <code>scheduler.Try</code> instance in
+the config file's <code>c['schedulers']</code> list. This lets the
+administrator control who may initiate these “trial” builds, which
+branches are eligible for trial builds, and which Builders should be
+used for them.
+
+   <p>The <code>TryScheduler</code> has various means to accept build requests:
+all of them enforce more security than the usual buildmaster ports do. 
+Any source code being built can be used to compromise the buildslave
+accounts, but in general that code must be checked out from the VC
+repository first, so only people with commit privileges can get
+control of the buildslaves. The usual force-build control channels can
+waste buildslave time but do not allow arbitrary commands to be
+executed by people who don't have those commit privileges. However,
+the source code patch that is provided with the trial build does not
+have to go through the VC system first, so it is important to make
+sure these builds cannot be abused by a non-committer to acquire as
+much control over the buildslaves as a committer has. Ideally, only
+developers who have commit access to the VC repository would be able
+to start trial builds, but unfortunately the buildmaster does not, in
+general, have access to VC system's user list.
+
+   <p>As a result, the <code>TryScheduler</code> requires a bit more
+configuration. There are currently two ways to set this up:
+
+     <dl>
+<dt><strong>jobdir (ssh)</strong><dd>
+This approach creates a command queue directory, called the
+“jobdir”, in the buildmaster's working directory. The buildmaster
+admin sets the ownership and permissions of this directory to only
+grant write access to the desired set of developers, all of whom must
+have accounts on the machine. The <code>buildbot try</code> command creates
+a special file containing the source stamp information and drops it in
+the jobdir, just like a standard maildir. When the buildmaster notices
+the new file, it unpacks the information inside and starts the builds.
+
+     <p>The config file entries used by 'buildbot try' either specify a local
+queuedir (for which write and mv are used) or a remote one (using scp
+and ssh).
+
+     <p>The advantage of this scheme is that it is quite secure, the
+disadvantage is that it requires fiddling outside the buildmaster
+config (to set the permissions on the jobdir correctly). If the
+buildmaster machine happens to also house the VC repository, then it
+can be fairly easy to keep the VC userlist in sync with the
+trial-build userlist. If they are on different machines, this will be
+much more of a hassle. It may also involve granting developer accounts
+on a machine that would not otherwise require them.
+
+     <p>To implement this, the buildslave invokes 'ssh -l username host
+buildbot tryserver ARGS', passing the patch contents over stdin. The
+arguments must include the inlet directory and the revision
+information.
+
+     <br><dt><strong>user+password (PB)</strong><dd>
+In this approach, each developer gets a username/password pair, which
+are all listed in the buildmaster's configuration file. When the
+developer runs <code>buildbot try</code>, their machine connects to the
+buildmaster via PB and authenticates themselves using that username
+and password, then sends a PB command to start the trial build.
+
+     <p>The advantage of this scheme is that the entire configuration is
+performed inside the buildmaster's config file. The disadvantages are
+that it is less secure (while the “cred” authentication system does
+not expose the password in plaintext over the wire, it does not offer
+most of the other security properties that SSH does. In addition, the
+buildmaster admin is responsible for maintaining the username/password
+list, adding and deleting entries as developers come and go.
+
+   </dl>
+
+   <p>For example, to set up the “jobdir” style of trial build, using a
+command queue directory of <span class="file">MASTERDIR/jobdir</span> (and assuming that
+all your project developers were members of the <code>developers</code> unix
+group), you would first create that directory (with <span class="command">mkdir
+MASTERDIR/jobdir; chgrp developers MASTERDIR/jobdir; chmod g+rwx,o-rwx
+MASTERDIR/jobdir</span>), and then use the following scheduler in the
+buildmaster's config file:
+
+<pre class="example">     from buildbot.scheduler import Try_Jobdir
+     s = Try_Jobdir("try1", ["full-linux", "full-netbsd", "full-OSX"],
+                    jobdir="jobdir")
+     c['schedulers'] = [s]
+</pre>
+   <p>Note that you must create the jobdir before telling the buildmaster to
+use this configuration, otherwise you will get an error. Also remember
+that the buildmaster must be able to read and write to the jobdir as
+well. Be sure to watch the <span class="file">twistd.log</span> file (see <a href="#Logfiles">Logfiles</a>)
+as you start using the jobdir, to make sure the buildmaster is happy
+with it.
+
+   <p>To use the username/password form of authentication, create a
+<code>Try_Userpass</code> instance instead. It takes the same
+<code>builderNames</code> argument as the <code>Try_Jobdir</code> form, but
+accepts an addtional <code>port</code> argument (to specify the TCP port to
+listen on) and a <code>userpass</code> list of username/password pairs to
+accept:
+
+<pre class="example">     from buildbot.scheduler import Try_Userpass
+     s = Try_Userpass("try2", ["full-linux", "full-netbsd", "full-OSX"],
+                      port=8031, userpass=[("alice","pw1"), ("bob", "pw2")] )
+     c['schedulers'] = [s]
+</pre>
+   <h3 class="heading">locating the master</h3>
+
+<p>The <span class="command">try</span> command needs to be told how to connect to the
+<code>TryScheduler</code>, and must know which of the authentication
+approaches described above is in use by the buildmaster. You specify
+the approach by using <span class="option">--connect=ssh</span> or <span class="option">--connect=pb</span>
+(or <code>try_connect = 'ssh'</code> or <code>try_connect = 'pb'</code> in
+<span class="file">.buildbot/options</span>).
+
+   <p>For the PB approach, the command must be given a <span class="option">--master</span>
+argument (in the form HOST:PORT) that points to TCP port that you
+picked in the <code>Try_Userpass</code> scheduler. It also takes a
+<span class="option">--username</span> and <span class="option">--passwd</span> pair of arguments that match
+one of the entries in the buildmaster's <code>userpass</code> list. These
+arguments can also be provided as <code>try_master</code>,
+<code>try_username</code>, and <code>try_password</code> entries in the
+<span class="file">.buildbot/options</span> file.
+
+   <p>For the SSH approach, the command must be given <span class="option">--tryhost</span>,
+<span class="option">--username</span>, and optionally <span class="option">--password</span> (TODO:
+really?) to get to the buildmaster host. It must also be given
+<span class="option">--trydir</span>, which points to the inlet directory configured
+above. The trydir can be relative to the user's home directory, but
+most of the time you will use an explicit path like
+<span class="file">~buildbot/project/trydir</span>. These arguments can be provided in
+<span class="file">.buildbot/options</span> as <code>try_host</code>, <code>try_username</code>,
+<code>try_password</code>, and <code>try_dir</code>.
+
+<h3 class="heading">choosing the Builders</h3>
+
+<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 TryScheduler's
+<code>builderNames=</code> 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>The set of Builders to use can be specified with multiple
+<span class="option">--builder</span> arguments on the command line. It can also be
+specified with a single <code>try_builders</code> option in
+<span class="file">.buildbot/options</span> that uses a list of strings to specify all
+the Builder names:
+
+<pre class="example">     try_builders = ["full-OSX", "full-win32", "full-linux"]
+</pre>
+   <h3 class="heading">specifying the VC system</h3>
+
+<p>The <span class="command">try</span> 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 <span class="command">try</span> command which VC system you are
+using, with an argument like <span class="option">--vc=cvs</span> or <span class="option">--vc=tla</span>. 
+This can also be provided as <code>try_vc</code> in
+<span class="file">.buildbot/options</span>.
+
+<h3 class="heading">finding the top of the tree</h3>
+
+<p>Some VC systems (notably CVS and SVN) track each directory
+more-or-less independently, which means the <span class="command">try</span> 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
+<span class="command">try</span> command will crawl up through the parent directories
+until it finds a marker file. The default name for this marker file is
+<span class="file">.buildbot-top</span>, so when you are using CVS or SVN you should
+<code>touch .buildbot-top</code> from the top of your tree before running
+<span class="command">buildbot try</span>. Alternatively, you can use a filename like
+<span class="file">ChangeLog</span> or <span class="file">README</span>, since many projects put one of
+these files in their top-most directory (and nowhere else). To set
+this filename, use <span class="option">--try-topfile=ChangeLog</span>, or set it in the
+options file with <code>try_topfile = 'ChangeLog'</code>.
+
+   <p>You can also manually set the top of the tree with
+<span class="option">--try-topdir=~/trees/mytree</span>, or <code>try_topdir =
+'~/trees/mytree'</code>. If you use <code>try_topdir</code>, in a
+<span class="file">.buildbot/options</span> file, you will need a separate options file
+for each tree you use, so it may be more convenient to use the
+<code>try_topfile</code> approach instead.
+
+   <p>If the <span class="command">try</span> command cannot find the top directory, it will
+abort with an error message. Other VC systems which work on full
+projects instead of individual directories (tla, baz, darcs, monotone)
+do not require <span class="command">try</span> to know the top directory, so the
+<span class="option">--try-topfile</span> and <span class="option">--try-topdir</span> arguments will be
+ignored.
+
+<h3 class="heading">determining the revision and patch</h3>
+
+<p>Each VC system has a separate approach for determining the tree's base
+revision and computing a patch.
+
+     <dl>
+<dt><code>CVS</code><dd>Wow, good question. We have to assume that you've done an <code>cvs
+update</code> on the whole tree... [TODO]
+
+     <br><dt><code>SVN</code><dd><span class="command">try</span> does a <code>svn status -u</code> to find the latest
+repository revision number (emitted on the last line in the “Status
+against revision: NN” message). It then performs an <code>svn diff
+-rNN</code> 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 “try” tree being created with
+the latest revision, then <em>backwards</em> patches applied to bring it
+“back” 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.
+
+     <br><dt><code>baz</code><dd><span class="command">try</span> does a <code>baz tree-id</code> to determine the
+fully-qualified version and patch identifier for the tree
+(ARCHIVE/VERSION–patch-NN), and uses the VERSION–patch-NN component
+as the base revision. It then does a <code>baz diff</code> to obtain the
+patch.
+
+     <br><dt><code>tla</code><dd><span class="command">try</span> does a <code>tla tree-version</code> to get the
+fully-qualified version identifier (ARCHIVE/VERSION), then takes the
+first line of <code>tla logs --reverse</code> to figure out the base
+revision. Then it does <code>tla changes --diffs</code> to obtain the patch.
+
+     <br><dt><code>darcs</code><dd><code>darcs changes --context</code> emits a text file that contains a list
+of all patches back to and including the last tag 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 “context” file <em>are</em> the revision stamp for a
+Darcs-controlled source tree.
+
+     <p>So <span class="command">try</span> does a <code>darcs changes --context</code> to determine
+what your tree's base revision is, and then does a <code>darcs diff
+-u</code> to compute the patch relative to that revision.
+
+     <!-- TODO: monotone, git -->
+<!-- TODO: new VC systems: mercurial (hg) -->
+</dl>
+
+<h3 class="heading">waiting for results</h3>
+
+<p>If you provide the <span class="option">--wait</span> option (or <code>try_wait = True</code>
+in <span class="file">.buildbot/options</span>), the <span class="command">buildbot try</span> command will
+wait until your changes have either been proven good or bad before
+exiting. Unless you use the <span class="option">--quiet</span> option (or
+<code>try_quiet=True</code>), it will emit a progress message every 60
+seconds until the builds have completed.
+
+<div class="node">
+<p><hr>
+<a name="Other-Tools"></a>Next: <a rel="next" accesskey="n" href="#_002ebuildbot-config-directory">.buildbot config directory</a>,
+Previous: <a rel="previous" accesskey="p" href="#Developer-Tools">Developer Tools</a>,
+Up: <a rel="up" accesskey="u" href="#Command_002dline-tool">Command-line tool</a>
+<br>
+</div>
+
+<h3 class="section">8.3 Other Tools</h3>
+
+<p>These tools are generally used by buildmaster administrators.
+
+<ul class="menu">
+<li><a accesskey="1" href="#sendchange">sendchange</a>
+<li><a accesskey="2" href="#debugclient">debugclient</a>
+</ul>
+
+<div class="node">
+<p><hr>
+<a name="sendchange"></a>Next: <a rel="next" accesskey="n" href="#debugclient">debugclient</a>,
+Previous: <a rel="previous" accesskey="p" href="#Other-Tools">Other Tools</a>,
+Up: <a rel="up" accesskey="u" href="#Other-Tools">Other Tools</a>
+<br>
+</div>
+
+<h4 class="subsection">8.3.1 sendchange</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.
+
+<pre class="example">     buildbot sendchange --master <var>MASTERHOST</var>:<var>PORT</var> --username <var>USER</var> <var>FILENAMES..</var>
+</pre>
+   <p>There are other (optional) arguments which can influence the
+<code>Change</code> that gets submitted:
+
+     <dl>
+<dt><code>--revision_number</code><dd>This provides a (numeric) revision number for the change, used for VC systems
+that use numeric transaction numbers (like Subversion).
+
+     <br><dt><code>--revision</code><dd>This provides a (string) revision specifier, for VC systems that use
+strings (Arch would use something like patch-42, Darcs would use the
+patch name, etc).
+
+     <br><dt><code>--comments</code><dd>This provides the change comments as a single argument. You may want
+to use <span class="option">--logfile</span> instead.
+
+     <br><dt><code>--logfile</code><dd>This instructs the tool to read the change comments from the given
+file. If you use <code>-</code> as the filename, the tool will read the
+change comments from stdin. 
+</dl>
+
+<div class="node">
+<p><hr>
+<a name="debugclient"></a>Previous: <a rel="previous" accesskey="p" href="#sendchange">sendchange</a>,
+Up: <a rel="up" accesskey="u" href="#Other-Tools">Other Tools</a>
+<br>
+</div>
+
+<h4 class="subsection">8.3.2 debugclient</h4>
+
+<pre class="example">     buildbot debugclient --master <var>MASTERHOST</var>:<var>PORT</var> --passwd <var>DEBUGPW</var>
+</pre>
+   <p>This launches a small Gtk+/Glade-based debug tool, connecting to the
+buildmaster's “debug port”. This debug port shares the same port
+number as the slaveport (see <a href="#Setting-the-slaveport">Setting the slaveport</a>), but the
+<code>debugPort</code> is only enabled if you set a debug password in the
+buildmaster's config file (see <a href="#Debug-options">Debug options</a>). The
+<span class="option">--passwd</span> option must match the <code>c['debugPassword']</code>
+value.
+
+   <p><span class="option">--master</span> can also be provided in <span class="file">.debug/options</span> by the
+<code>master</code> key. <span class="option">--passwd</span> can be provided by the
+<code>debugPassword</code> key.
+
+   <p>The <code>Connect</code> 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:
+
+     <dl>
+<dt><code>Reload .cfg</code><dd>Forces the buildmaster to reload its <span class="file">master.cfg</span> 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 <span class="file">twistd.log</span> as you reload the config
+file, as any errors which are detected in the config file will be
+announced there.
+
+     <br><dt><code>Rebuild .py</code><dd>(not yet implemented). The idea here is to use Twisted's “rebuild”
+facilities to replace the buildmaster's running code with a new
+version. Even if this worked, it would only be used by buildbot
+developers.
+
+     <br><dt><code>poke IRC</code><dd>This locates a <code>words.IRC</code> 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.
+
+     <br><dt><code>Commit</code><dd>This allows you to inject a Change, 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.
+
+     <br><dt><code>Force Build</code><dd>This lets you force a Builder (selected by name) to start a build of
+the current source tree.
+
+     <br><dt><code>Currently</code><dd>(obsolete). This was used to manually set the status of the given
+Builder, but the status-assignment code was changed in an incompatible
+way and these buttons are no longer meaningful.
+
+   </dl>
+
+<div class="node">
+<p><hr>
+<a name="_002ebuildbot-config-directory"></a>Previous: <a rel="previous" accesskey="p" href="#Other-Tools">Other Tools</a>,
+Up: <a rel="up" accesskey="u" href="#Command_002dline-tool">Command-line tool</a>
+<br>
+</div>
+
+<h3 class="section">8.4 .buildbot config directory</h3>
+
+<p>Many of the <span class="command">buildbot</span> 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 “options” file. The <span class="command">buildbot</span>
+command will look for a special directory named <span class="file">.buildbot</span>,
+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 <span class="file">options</span> in this directory, and will
+evaluate it as a python script, looking for certain names to be set. 
+You can just put simple <code>name = 'value'</code> pairs in this file to
+set the options.
+
+   <p>For a description of the names used in this file, please see the
+documentation for the individual <span class="command">buildbot</span> sub-commands. The
+following is a brief sample of what this file's contents could be.
+
+<pre class="example">     # for status-reading tools
+     masterstatus = 'buildbot.example.org:12345'
+     # for 'sendchange' or the debug port
+     master = 'buildbot.example.org:18990'
+     debugPassword = 'eiv7Po'
+</pre>
+     <dl>
+<dt><code>masterstatus</code><dd>Location of the <code>client.PBListener</code> status port, used by
+<span class="command">statuslog</span> and <span class="command">statusgui</span>.
+
+     <br><dt><code>master</code><dd>Location of the <code>debugPort</code> (for <span class="command">debugclient</span>). Also the
+location of the <code>pb.PBChangeSource</code> (for <span class="command">sendchange</span>). 
+Usually shares the slaveport, but a future version may make it
+possible to have these listen on a separate port number.
+
+     <br><dt><code>debugPassword</code><dd>Must match the value of <code>c['debugPassword']</code>, used to protect the
+debug port, for the <span class="command">debugclient</span> command.
+
+     <br><dt><code>username</code><dd>Provides a default username for the <span class="command">sendchange</span> command.
+
+   </dl>
+
+<div class="node">
+<p><hr>
+<a name="Resources"></a>Next: <a rel="next" accesskey="n" href="#Developer_0027s-Appendix">Developer's Appendix</a>,
+Previous: <a rel="previous" accesskey="p" href="#Command_002dline-tool">Command-line tool</a>,
+Up: <a rel="up" accesskey="u" href="#Top">Top</a>
+<br>
+</div>
+
+<h2 class="chapter">9 Resources</h2>
 
 <p>The Buildbot's home page is at <a href="http://buildbot.sourceforge.net/">http://buildbot.sourceforge.net/</a>
 





More information about the Commits mailing list