| OLD | NEW |
|---|
| (Empty) |
| 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 and python-2.6. | |
| 57 | |
| 58 Twisted: http://twistedmatrix.com | |
| 59 | |
| 60 Both the buildmaster and the buildslaves require Twisted-2.5.x or later. | |
| 61 As always, the most recent version is recommended. It has been tested | |
| 62 against Twisted-2.5.0 and Twisted-8.0.1 through Twisted-8.2.0. | |
| 63 | |
| 64 Certain versions of Twisted are delivered as a collection of subpackages. | |
| 65 You'll need at least "Twisted" (the core package), and you'll also want | |
| 66 TwistedMail, TwistedWeb, and TwistedWords (for sending email, serving a | |
| 67 web status page, and delivering build status via IRC, respectively). You | |
| 68 might also want TwistedConch (for the encrypted Manhole debug port). Note | |
| 69 that 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 a whole bunch of tests, depending upon what VC tools you have | |
| 83 irstalled. 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 the | |
| 86 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 report | |
| 88 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. | |
| 183 | |
| 184 | |
| 185 COPYING: | |
| 186 | |
| 187 Buildbot is free software: you can redistribute it and/or modify it under | |
| 188 the terms of the GNU General Public License as published by the Free | |
| 189 Software Foundation, version 2. | |
| 190 | |
| 191 This program is distributed in the hope that it will be useful, but | |
| 192 WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 193 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General | |
| 194 Public License for more details. | |
| 195 | |
| 196 For full details, please see the file named COPYING in the top directory | |
| 197 of the source tree. You should have received a copy of the GNU General | |
| 198 Public License along with this program. If not, see | |
| 199 <http://www.gnu.org/licenses/>. | |
| 200 | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 12207158:
Bye bye buildbot 0.7.12. (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/tools/build