README

   1
   2 BuildBot: build/test automation
   3   http://buildbot.net
   4   Brian Warner <warner-buildbot @ lothar . com>
   5
   6
   7 Abstract:
   8
   9 The BuildBot is a system to automate the compile/test cycle required by most
  10 software projects to validate code changes. By automatically rebuilding and
  11 testing the tree each time something has changed, build problems are
  12 pinpointed quickly, before other developers are inconvenienced by the
  13 failure. The guilty developer can be identified and harassed without human
  14 intervention. By running the builds on a variety of platforms, developers
  15 who do not have the facilities to test their changes everywhere before
  16 checkin will at least know shortly afterwards whether they have broken the
  17 build or not. Warning counts, lint checks, image size, compile time, and
  18 other build parameters can be tracked over time, are more visible, and
  19 are therefore easier to improve.
  20
  21 The overall goal is to reduce tree breakage and provide a platform to run
  22 tests or code-quality checks that are too annoying or pedantic for any human
  23 to waste their time with. Developers get immediate (and potentially public)
  24 feedback about their changes, encouraging them to be more careful about
  25 testing before checkin.
  26
  27
  28 Features:
  29
  30  * run builds on a variety of slave platforms
  31  * arbitrary build process: handles projects using C, Python, whatever
  32  * minimal host requirements: python and Twisted
  33  * slaves can be behind a firewall if they can still do checkout
  34  * status delivery through web page, email, IRC, other protocols
  35  * track builds in progress, provide estimated completion time
  36  * flexible configuration by subclassing generic build process classes
  37  * debug tools to force a new build, submit fake Changes, query slave status
  38  * released under the GPL
  39
  40
  41 DOCUMENTATION:
  42
  43 The PyCon paper has a good description of the overall architecture. It is
  44 available in HTML form in docs/PyCon-2003/buildbot.html, or on the web page.
  45
  46 The User's Manual is in docs/buildbot.info, and the Installation chapter is
  47 the best guide to use for setup instructions. The .texinfo source can also be
  48 turned into printed documentation. An HTML representation is available on the
  49 Buildbot home page.
  50
  51 REQUIREMENTS:
  52
  53  Python: http://www.python.org
  54
  55    Buildbot requires python-2.3 or later, and is primarily developed against
  56    python-2.4 . It is also tested against python-2.5 .
  57
  58  Twisted: http://twistedmatrix.com
  59
  60    Both the buildmaster and the buildslaves require Twisted-2.0.x or later.
  61    As always, the most recent version is recommended. It has been tested
  62    against Twisted-2.5.0 and Twisted SVN as of the date of release.
  63
  64    Twisted is delivered as a collection of subpackages. You'll need at least
  65    "Twisted" (the core package), and you'll also want TwistedMail,
  66    TwistedWeb, and TwistedWords (for sending email, serving a web status
  67    page, and delivering build status via IRC, respectively). You might also
  68    want TwistedConch (for the encrypted Manhole debug port). Note that
  69    Twisted requires ZopeInterface to be installed as well.
  70
  71 INSTALLATION:
  72
  73 Please read the User's Manual in docs/buildbot.info or docs/buildbot.html for
  74 complete instructions. This file only contains a brief summary.
  75
  76  RUNNING THE UNIT TESTS
  77
  78 If you would like to run the unit test suite, use a command like this:
  79
  80  PYTHONPATH=. trial buildbot.test
  81
  82 This should run up to 221 tests, depending upon what VC tools you have
  83 installed. On my desktop machine it takes about six minutes to complete.
  84 Nothing should fail (at least under unix), a few might be skipped. If any of
  85 the tests fail, you should stop and investigate the cause before continuing
  86 the installation process, as it will probably be easier to track down the bug
  87 early. There are a few known failures under windows and OS-X, but please
  88 report these to the mailing list so we can isolate and resolve them.
  89
  90 Neither CVS nor SVN support file based repositories on network filesystem
  91 (or network drives in Windows parlance). Therefore it is recommended to run
  92 all unit tests on local hard disks.
  93
  94  INSTALLING THE LIBRARIES:
  95
  96 The first step is to install the python libraries. This package uses the
  97 standard 'distutils' module, so installing them is usually a matter of
  98 doing something like:
  99
 100  python ./setup.py install
 101
 102 To test this, shift to a different directory (like /tmp), and run:
 103
 104  buildbot --version
 105
 106 If it announces the versions of Buildbot and Twisted, the install went ok.
 107
 108
 109  SETTING UP A BUILD SLAVE:
 110
 111 If you want to run a build slave, you need to obtain the following pieces of
 112 information from the administrator of the buildmaster you intend to connect
 113 to:
 114
 115  your buildslave's name
 116  the password assigned to your buildslave
 117  the hostname and port number of the buildmaster, i.e. example.com:8007
 118
 119 You also need to pick a working directory for the buildslave. All commands
 120 will be run inside this directory.
 121
 122 Now run the 'buildbot' command as follows:
 123
 124  buildbot create-slave WORKDIR MASTERHOST:PORT SLAVENAME PASSWORD
 125
 126 This will create a file called "buildbot.tac", which bundles up all the state
 127 needed by the build slave application. Twisted has a tool called "twistd"
 128 which knows how to load these saved applications and start running them.
 129 twistd takes care of logging and daemonization (running the program in the
 130 background). /usr/bin/buildbot is a front end which runs twistd for you.
 131
 132 Once you've set up the directory with the .tac file, you start it running
 133 like this:
 134
 135  buildbot start WORKDIR
 136
 137 This will start the build slave in the background and finish, so you don't
 138 need to put it in the background yourself with "&". The process ID of the
 139 background task is written to a file called "twistd.pid", and all output from
 140 the program is written to a log file named "twistd.log". Look in twistd.log
 141 to make sure the buildslave has started.
 142
 143 To shut down the build slave, use:
 144
 145  buildbot stop WORKDIR
 146
 147
 148  RUNNING BEHIND A NAT BOX:
 149
 150 Some network environments will not properly maintain a TCP connection that
 151 appears to be idle. NAT boxes which do some form of connection tracking may
 152 drop the port mapping if it looks like the TCP session has been idle for too
 153 long. The buildslave attempts to turn on TCP "keepalives" (supported by
 154 Twisted 1.0.6 and later), and if these cannot be activated, it uses
 155 application level keepalives (which send a dummy message to the build master
 156 on a periodic basis). The TCP keepalive is typically sent at intervals of
 157 about 2 hours, and is configurable through the kernel. The application-level
 158 keepalive defaults to running once every 10 minutes.
 159
 160 To manually turn on application-level keepalives, or to set them to use some
 161 other interval, add "--keepalive NNN" to the 'buildbot slave' command line.
 162 NNN is the number of seconds between keepalives. Use as large a value as your
 163 NAT box allows to reduce the amount of unnecessary traffic on the wire. 600
 164 seconds (10 minutes) is a reasonable value.
 165
 166
 167  SETTING UP A BUILD MASTER:
 168
 169 Please read the user's manual for instructions. The short form is that you
 170 use 'buildbot create-master MASTERDIR' to create the base directory, then you
 171 edit the 'master.cfg' file to configure the buildmaster. Once this is ready,
 172 you use 'buildbot start MASTERDIR' to launch it.
 173
 174 A sample configuration file will be created for you in WORKDIR/master.cfg .
 175 There are more examples in docs/examples/, and plenty of documentation in the
 176 user's manual. Everything is controlled by the config file.
 177
 178
 179 SUPPORT:
 180
 181  Please send questions, bugs, patches, etc, to the buildbot-devel mailing
 182  list reachable through http://buildbot.net/, so that everyone can see them.