master/README

   1
   2 BuildBot: build/test automation
   3   http://buildbot.net
   4   Brian Warner <warner-buildbot @ lothar . com>
   5   Dustin J. Mitchell <dustin@v.igoro.us>
   6
   7
   8 Abstract:
   9
  10 The BuildBot is a system to automate the compile/test cycle required by most
  11 software projects to validate code changes. By automatically rebuilding and
  12 testing the tree each time something has changed, build problems are
  13 pinpointed quickly, before other developers are inconvenienced by the
  14 failure. The guilty developer can be identified and harassed without human
  15 intervention. By running the builds on a variety of platforms, developers
  16 who do not have the facilities to test their changes everywhere before
  17 checkin will at least know shortly afterwards whether they have broken the
  18 build or not. Warning counts, lint checks, image size, compile time, and
  19 other build parameters can be tracked over time, are more visible, and
  20 are therefore easier to improve.
  21
  22 The overall goal is to reduce tree breakage and provide a platform to run
  23 tests or code-quality checks that are too annoying or pedantic for any human
  24 to waste their time with. Developers get immediate (and potentially public)
  25 feedback about their changes, encouraging them to be more careful about
  26 testing before checkin.
  27
  28
  29 Features:
  30
  31  * run builds on a variety of slave platforms
  32  * arbitrary build process: handles projects using C, Python, whatever
  33  * minimal host requirements: python and Twisted
  34  * slaves can be behind a firewall if they can still do checkout
  35  * status delivery through web page, email, IRC, other protocols
  36  * track builds in progress, provide estimated completion time
  37  * flexible configuration by subclassing generic build process classes
  38  * debug tools to force a new build, submit fake Changes, query slave status
  39  * released under the GPL
  40
  41
  42 DOCUMENTATION:
  43
  44 The PyCon paper has a good description of the overall architecture. It is
  45 available in HTML form in docs/PyCon-2003/buildbot.html, or on the web page.
  46
  47 The User's Manual is in docs/buildbot.info, and the Installation chapter is
  48 the best guide to use for setup instructions. The .texinfo source can also be
  49 turned into printed documentation. An HTML representation is available on the
  50 Buildbot home page.
  51
  52 REQUIREMENTS:
  53
  54   Briefly: python, Twisted, Jinja, simplejson, and SQLite.  Simplejson and
  55   SQLite are included with recent versions of Python.
  56
  57   See http://djmitche.github.com/buildbot/docs/current/Requirements.html for
  58   details.
  59
  60 INSTALLATION:
  61
  62 Please read the User's Manual in docs/buildbot.info or docs/buildbot.html for
  63 complete instructions. This file only contains a brief summary.
  64
  65  INSTALLING THE LIBRARIES:
  66
  67 The first step is to install the python libraries. This package uses the
  68 standard 'distutils' module, so installing them is usually a matter of
  69 doing something like:
  70
  71  python ./setup.py install
  72
  73 To test this, shift to a different directory (like /tmp), and run:
  74
  75  buildbot --version
  76
  77 If it announces the versions of Buildbot and Twisted, the install went ok.
  78
  79
  80  SETTING UP A BUILD SLAVE:
  81
  82 If you want to run a build slave, you need to obtain the following pieces of
  83 information from the administrator of the buildmaster you intend to connect
  84 to:
  85
  86  your buildslave's name
  87  the password assigned to your buildslave
  88  the hostname and port number of the buildmaster, i.e. example.com:8007
  89
  90 You also need to pick a working directory for the buildslave. All commands
  91 will be run inside this directory.
  92
  93 Now run the 'buildslave' command as follows:
  94
  95  buildslave create-slave WORKDIR MASTERHOST:PORT SLAVENAME PASSWORD
  96
  97 This will create a file called "buildbot.tac", which bundles up all the state
  98 needed by the build slave application. Twisted has a tool called "twistd"
  99 which knows how to load these saved applications and start running them.
 100 twistd takes care of logging and daemonization (running the program in the
 101 background). /usr/bin/buildbot is a front end which runs twistd for you.
 102
 103 Once you've set up the directory with the .tac file, you start it running
 104 like this:
 105
 106  buildslave start WORKDIR
 107
 108 This will start the build slave in the background and finish, so you don't
 109 need to put it in the background yourself with "&". The process ID of the
 110 background task is written to a file called "twistd.pid", and all output from
 111 the program is written to a log file named "twistd.log". Look in twistd.log
 112 to make sure the buildslave has started.
 113
 114 To shut down the build slave, use:
 115
 116  buildslave stop WORKDIR
 117
 118
 119  RUNNING BEHIND A NAT BOX:
 120
 121 Some network environments will not properly maintain a TCP connection that
 122 appears to be idle. NAT boxes which do some form of connection tracking may
 123 drop the port mapping if it looks like the TCP session has been idle for too
 124 long. The buildslave attempts to turn on TCP "keepalives" (supported by
 125 Twisted 1.0.6 and later), and if these cannot be activated, it uses
 126 application level keepalives (which send a dummy message to the build master
 127 on a periodic basis). The TCP keepalive is typically sent at intervals of
 128 about 2 hours, and is configurable through the kernel. The application-level
 129 keepalive defaults to running once every 10 minutes.
 130
 131 To manually turn on application-level keepalives, or to set them to use some
 132 other interval, add "--keepalive NNN" to the 'buildbot slave' command line.
 133 NNN is the number of seconds between keepalives. Use as large a value as your
 134 NAT box allows to reduce the amount of unnecessary traffic on the wire. 600
 135 seconds (10 minutes) is a reasonable value.
 136
 137
 138  SETTING UP A BUILD MASTER:
 139
 140 Please read the user's manual for instructions. The short form is that you
 141 use 'buildbot create-master MASTERDIR' to create the base directory, then you
 142 edit the 'master.cfg' file to configure the buildmaster. Once this is ready,
 143 you use 'buildbot start MASTERDIR' to launch it.
 144
 145 A sample configuration file will be created for you in WORKDIR/master.cfg .
 146 There are more examples in docs/examples/, and plenty of documentation in the
 147 user's manual. Everything is controlled by the config file.
 148
 149
 150 SUPPORT:
 151
 152  Please send questions, bugs, patches, etc, to the buildbot-devel mailing
 153  list reachable through http://buildbot.net/, so that everyone can see them.
 154
 155
 156 CONTRIBUTE:
 157
 158  If you are considering contributing to Buildbot please look at
 159  http://buildbot.net/trac/wiki/Development to understand the workflow.
 160
 161
 162 COPYING:
 163
 164     Buildbot is free software: you can redistribute it and/or modify it under
 165     the terms of the GNU General Public License as published by the Free
 166     Software Foundation, version 2.
 167
 168     This program is distributed in the hope that it will be useful, but
 169     WITHOUT ANY WARRANTY; without even the implied warranty of
 170     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 171     Public License for more details.
 172
 173     For full details, please see the file named COPYING in the top directory
 174     of the source tree. You should have received a copy of the GNU General
 175     Public License along with this program. If not, see
 176     <http://www.gnu.org/licenses/>.
 177