(refs #35) fix dependent scheduler re-checking: make calculation of upstream lazier
[buildbot.git] / README
blob15a60249b6f70c215ee7d26b653acc33eb8b21f9
2 BuildBot: build/test automation
3   http://buildbot.net
4   Brian Warner <warner-buildbot @ lothar . com>
7 Abstract:
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.
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.
28 Features:
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
41 DOCUMENTATION:
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.
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.
51 REQUIREMENTS:
53  Python: http://www.python.org
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 .
58  Twisted: http://twistedmatrix.com
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, Twisted-8.0.1, Twisted-8.1.0, and Twisted SVN as of
63    the date of release.
65    Certain versions of Twisted are delivered as a collection of subpackages.
66    You'll need at least "Twisted" (the core package), and you'll also want
67    TwistedMail, TwistedWeb, and TwistedWords (for sending email, serving a
68    web status page, and delivering build status via IRC, respectively). You
69    might also want TwistedConch (for the encrypted Manhole debug port). Note
70    that Twisted requires ZopeInterface to be installed as well.
72 INSTALLATION:
74 Please read the User's Manual in docs/buildbot.info or docs/buildbot.html for
75 complete instructions. This file only contains a brief summary.
77  RUNNING THE UNIT TESTS
79 If you would like to run the unit test suite, use a command like this:
81  PYTHONPATH=. trial buildbot.test
83 This should run up to 221 tests, depending upon what VC tools you have
84 installed. On my desktop machine it takes about six minutes to complete.
85 Nothing should fail (at least under unix), a few might be skipped. If any of
86 the tests fail, you should stop and investigate the cause before continuing
87 the installation process, as it will probably be easier to track down the bug
88 early. There are a few known failures under windows and OS-X, but please
89 report these to the mailing list so we can isolate and resolve them.
91 Neither CVS nor SVN support file based repositories on network filesystem
92 (or network drives in Windows parlance). Therefore it is recommended to run
93 all unit tests on local hard disks.
95  INSTALLING THE LIBRARIES:
97 The first step is to install the python libraries. This package uses the
98 standard 'distutils' module, so installing them is usually a matter of
99 doing something like:
101  python ./setup.py install
103 To test this, shift to a different directory (like /tmp), and run:
105  buildbot --version
107 If it announces the versions of Buildbot and Twisted, the install went ok.
110  SETTING UP A BUILD SLAVE:
112 If you want to run a build slave, you need to obtain the following pieces of
113 information from the administrator of the buildmaster you intend to connect
116  your buildslave's name
117  the password assigned to your buildslave
118  the hostname and port number of the buildmaster, i.e. example.com:8007
120 You also need to pick a working directory for the buildslave. All commands
121 will be run inside this directory.
123 Now run the 'buildbot' command as follows:
125  buildbot create-slave WORKDIR MASTERHOST:PORT SLAVENAME PASSWORD
127 This will create a file called "buildbot.tac", which bundles up all the state
128 needed by the build slave application. Twisted has a tool called "twistd"
129 which knows how to load these saved applications and start running them.
130 twistd takes care of logging and daemonization (running the program in the
131 background). /usr/bin/buildbot is a front end which runs twistd for you.
133 Once you've set up the directory with the .tac file, you start it running
134 like this:
136  buildbot start WORKDIR
138 This will start the build slave in the background and finish, so you don't
139 need to put it in the background yourself with "&". The process ID of the
140 background task is written to a file called "twistd.pid", and all output from
141 the program is written to a log file named "twistd.log". Look in twistd.log
142 to make sure the buildslave has started.
144 To shut down the build slave, use:
146  buildbot stop WORKDIR
149  RUNNING BEHIND A NAT BOX:
151 Some network environments will not properly maintain a TCP connection that
152 appears to be idle. NAT boxes which do some form of connection tracking may
153 drop the port mapping if it looks like the TCP session has been idle for too
154 long. The buildslave attempts to turn on TCP "keepalives" (supported by
155 Twisted 1.0.6 and later), and if these cannot be activated, it uses
156 application level keepalives (which send a dummy message to the build master
157 on a periodic basis). The TCP keepalive is typically sent at intervals of
158 about 2 hours, and is configurable through the kernel. The application-level
159 keepalive defaults to running once every 10 minutes.
161 To manually turn on application-level keepalives, or to set them to use some
162 other interval, add "--keepalive NNN" to the 'buildbot slave' command line.
163 NNN is the number of seconds between keepalives. Use as large a value as your
164 NAT box allows to reduce the amount of unnecessary traffic on the wire. 600
165 seconds (10 minutes) is a reasonable value.
168  SETTING UP A BUILD MASTER:
170 Please read the user's manual for instructions. The short form is that you
171 use 'buildbot create-master MASTERDIR' to create the base directory, then you
172 edit the 'master.cfg' file to configure the buildmaster. Once this is ready,
173 you use 'buildbot start MASTERDIR' to launch it.
175 A sample configuration file will be created for you in WORKDIR/master.cfg .
176 There are more examples in docs/examples/, and plenty of documentation in the
177 user's manual. Everything is controlled by the config file.
180 SUPPORT:
182  Please send questions, bugs, patches, etc, to the buildbot-devel mailing
183  list reachable through http://buildbot.net/, so that everyone can see them.
186 COPYING:
188     Buildbot is free software: you can redistribute it and/or modify it under
189     the terms of the GNU General Public License as published by the Free
190     Software Foundation, version 2.
192     This program is distributed in the hope that it will be useful, but
193     WITHOUT ANY WARRANTY; without even the implied warranty of
194     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
195     Public License for more details.
197     For full details, please see the file named COPYING in the top directory
198     of the source tree. You should have received a copy of the GNU General
199     Public License along with this program. If not, see
200     <http://www.gnu.org/licenses/>.