1 \input texinfo @c -*-texinfo-*-
3 @setfilename buildbot.info
4 @settitle BuildBot Manual 0.7.9
13 @c these indices are for classes useful in a master.cfg config file
14 @c @csindex : Change Sources
15 @c @slindex : Schedulers and Locks
16 @c @bfindex : Build Factories
17 @c @bsindex : Build Steps
18 @c @stindex : Status Targets
20 @c @bcindex : keys that make up BuildmasterConfig
23 This is the BuildBot manual.
25 Copyright (C) 2005,2006 Brian Warner
27 Copying and distribution of this file, with or without
28 modification, are permitted in any medium without royalty
29 provided the copyright notice and this notice are preserved.
36 @vskip 0pt plus 1filll
40 @c Output the table of the contents at the beginning.
44 @node Top, Introduction, (dir), (dir)
51 * Introduction:: What the BuildBot does.
52 * Installation:: Creating a buildmaster and buildslaves,
54 * Concepts:: What goes on in the buildbot's little mind.
55 * Configuration:: Controlling the buildbot.
56 * Getting Source Code Changes:: Discovering when to run a build.
57 * Build Process:: Controlling how each build is run.
58 * Status Delivery:: Telling the world about the build's results.
60 * Resources:: Getting help.
61 * Developer's Appendix::
62 * Index of Useful Classes::
63 * Index of master.cfg keys::
64 * Index:: Complete index.
67 --- The Detailed Node Listing ---
71 * History and Philosophy::
72 * System Architecture::
77 * BuildSlave Connections::
78 * Buildmaster Architecture::
79 * Status Delivery Architecture::
84 * Installing the code::
85 * Creating a buildmaster::
86 * Upgrading an Existing Buildmaster::
87 * Creating a buildslave::
88 * Launching the daemons::
96 * Buildslave Options::
100 * Starting the buildslave::
101 * Connecting to the buildmaster::
106 * Version Control Systems::
114 Version Control Systems
116 * Generalizing VC Systems::
117 * Source Tree Specifications::
118 * How Different VC Systems Specify Sources::
119 * Attributes of Changes::
123 * Doing Things With Users::
126 * Live Status Clients::
130 * Config File Format::
131 * Loading the Config File::
132 * Testing the Config File::
133 * Defining the Project::
134 * Change Sources and Schedulers::
135 * Setting the slaveport::
136 * Buildslave Specifiers::
137 * On-Demand ("Latent") Buildslaves::
138 * Defining Global Properties::
139 * Defining Builders::
140 * Defining Status Targets::
143 Change Sources and Schedulers
145 * Scheduler Scheduler::
146 * AnyBranchScheduler::
147 * Dependent Scheduler::
148 * Periodic Scheduler::
149 * Nightly Scheduler::
151 * Triggerable Scheduler::
153 Buildslave Specifiers
154 * When Buildslaves Go Missing::
156 On-Demand ("Latent") Buildslaves
157 * Amazon Web Services Elastic Compute Cloud ("AWS EC2")::
158 * Dangers with Latent Buildslaves::
159 * Writing New Latent Buildslaves::
161 Getting Source Code Changes
164 * Choosing ChangeSources::
165 * CVSToys - PBService::
166 * Mail-parsing ChangeSources::
175 Mail-parsing ChangeSources
177 * Subscribing the Buildmaster::
179 * Parsing Email Change Messages::
181 Parsing Email Change Messages
184 * SyncmailMaildirSource::
185 * BonsaiMaildirSource::
186 * SVNCommitEmailMaildirSource::
196 * Common Parameters::
197 * Using Build Properties::
200 * Simple ShellCommand Subclasses::
201 * Python BuildSteps::
202 * Transferring Files::
203 * Steps That Run on the Master::
204 * Triggering Schedulers::
205 * Writing New BuildSteps::
219 Simple ShellCommand Subclasses
234 Writing New BuildSteps
236 * BuildStep LogFiles::
238 * Adding LogObservers::
243 * BuildStep Objects::
245 * Process-Specific build factories::
249 * BuildFactory Attributes::
254 * BuildFactory Attributes::
257 Process-Specific build factories
262 * Python/Twisted/trial projects::
270 * Writing New Status Plugins::
274 * WebStatus Configuration Parameters::
275 * Buildbot Web Resources::
281 * Administrator Tools::
284 * .buildbot config directory::
304 @node Introduction, Installation, Top, Top
305 @chapter Introduction
309 The BuildBot is a system to automate the compile/test cycle required by most
310 software projects to validate code changes. By automatically rebuilding and
311 testing the tree each time something has changed, build problems are
312 pinpointed quickly, before other developers are inconvenienced by the
313 failure. The guilty developer can be identified and harassed without human
314 intervention. By running the builds on a variety of platforms, developers
315 who do not have the facilities to test their changes everywhere before
316 checkin will at least know shortly afterwards whether they have broken the
317 build or not. Warning counts, lint checks, image size, compile time, and
318 other build parameters can be tracked over time, are more visible, and
319 are therefore easier to improve.
321 The overall goal is to reduce tree breakage and provide a platform to
322 run tests or code-quality checks that are too annoying or pedantic for
323 any human to waste their time with. Developers get immediate (and
324 potentially public) feedback about their changes, encouraging them to
325 be more careful about testing before checkin.
331 run builds on a variety of slave platforms
333 arbitrary build process: handles projects using C, Python, whatever
335 minimal host requirements: python and Twisted
337 slaves can be behind a firewall if they can still do checkout
339 status delivery through web page, email, IRC, other protocols
341 track builds in progress, provide estimated completion time
343 flexible configuration by subclassing generic build process classes
345 debug tools to force a new build, submit fake Changes, query slave status
347 released under the GPL
351 * History and Philosophy::
352 * System Architecture::
357 @node History and Philosophy, System Architecture, Introduction, Introduction
358 @section History and Philosophy
360 @cindex Philosophy of operation
362 The Buildbot was inspired by a similar project built for a development
363 team writing a cross-platform embedded system. The various components
364 of the project were supposed to compile and run on several flavors of
365 unix (linux, solaris, BSD), but individual developers had their own
366 preferences and tended to stick to a single platform. From time to
367 time, incompatibilities would sneak in (some unix platforms want to
368 use @code{string.h}, some prefer @code{strings.h}), and then the tree
369 would compile for some developers but not others. The buildbot was
370 written to automate the human process of walking into the office,
371 updating a tree, compiling (and discovering the breakage), finding the
372 developer at fault, and complaining to them about the problem they had
373 introduced. With multiple platforms it was difficult for developers to
374 do the right thing (compile their potential change on all platforms);
375 the buildbot offered a way to help.
377 Another problem was when programmers would change the behavior of a
378 library without warning its users, or change internal aspects that
379 other code was (unfortunately) depending upon. Adding unit tests to
380 the codebase helps here: if an application's unit tests pass despite
381 changes in the libraries it uses, you can have more confidence that
382 the library changes haven't broken anything. Many developers
383 complained that the unit tests were inconvenient or took too long to
384 run: having the buildbot run them reduces the developer's workload to
387 In general, having more visibility into the project is always good,
388 and automation makes it easier for developers to do the right thing.
389 When everyone can see the status of the project, developers are
390 encouraged to keep the tree in good working order. Unit tests that
391 aren't run on a regular basis tend to suffer from bitrot just like
392 code does: exercising them on a regular basis helps to keep them
393 functioning and useful.
395 The current version of the Buildbot is additionally targeted at
396 distributed free-software projects, where resources and platforms are
397 only available when provided by interested volunteers. The buildslaves
398 are designed to require an absolute minimum of configuration, reducing
399 the effort a potential volunteer needs to expend to be able to
400 contribute a new test environment to the project. The goal is for
401 anyone who wishes that a given project would run on their favorite
402 platform should be able to offer that project a buildslave, running on
403 that platform, where they can verify that their portability code
404 works, and keeps working.
406 @node System Architecture, Control Flow, History and Philosophy, Introduction
407 @comment node-name, next, previous, up
408 @section System Architecture
410 The Buildbot consists of a single @code{buildmaster} and one or more
411 @code{buildslaves}, connected in a star topology. The buildmaster
412 makes all decisions about what, when, and how to build. It sends
413 commands to be run on the build slaves, which simply execute the
414 commands and return the results. (certain steps involve more local
415 decision making, where the overhead of sending a lot of commands back
416 and forth would be inappropriate, but in general the buildmaster is
417 responsible for everything).
419 The buildmaster is usually fed @code{Changes} by some sort of version
420 control system (@pxref{Change Sources}), which may cause builds to be
421 run. As the builds are performed, various status messages are
422 produced, which are then sent to any registered Status Targets
423 (@pxref{Status Delivery}).
425 @c @image{FILENAME, WIDTH, HEIGHT, ALTTEXT, EXTENSION}
426 @image{images/overview,,,Overview Diagram,}
428 The buildmaster is configured and maintained by the ``buildmaster
429 admin'', who is generally the project team member responsible for
430 build process issues. Each buildslave is maintained by a ``buildslave
431 admin'', who do not need to be quite as involved. Generally slaves are
432 run by anyone who has an interest in seeing the project work well on
433 their favorite platform.
436 * BuildSlave Connections::
437 * Buildmaster Architecture::
438 * Status Delivery Architecture::
441 @node BuildSlave Connections, Buildmaster Architecture, System Architecture, System Architecture
442 @subsection BuildSlave Connections
444 The buildslaves are typically run on a variety of separate machines,
445 at least one per platform of interest. These machines connect to the
446 buildmaster over a TCP connection to a publically-visible port. As a
447 result, the buildslaves can live behind a NAT box or similar
448 firewalls, as long as they can get to buildmaster. The TCP connections
449 are initiated by the buildslave and accepted by the buildmaster, but
450 commands and results travel both ways within this connection. The
451 buildmaster is always in charge, so all commands travel exclusively
452 from the buildmaster to the buildslave.
454 To perform builds, the buildslaves must typically obtain source code
455 from a CVS/SVN/etc repository. Therefore they must also be able to
456 reach the repository. The buildmaster provides instructions for
457 performing builds, but does not provide the source code itself.
459 @image{images/slaves,,,BuildSlave Connections,}
461 @node Buildmaster Architecture, Status Delivery Architecture, BuildSlave Connections, System Architecture
462 @subsection Buildmaster Architecture
464 The Buildmaster consists of several pieces:
466 @image{images/master,,,BuildMaster Architecture,}
471 Change Sources, which create a Change object each time something is
472 modified in the VC repository. Most ChangeSources listen for messages
473 from a hook script of some sort. Some sources actively poll the
474 repository on a regular basis. All Changes are fed to the Schedulers.
477 Schedulers, which decide when builds should be performed. They collect
478 Changes into BuildRequests, which are then queued for delivery to
479 Builders until a buildslave is available.
482 Builders, which control exactly @emph{how} each build is performed
483 (with a series of BuildSteps, configured in a BuildFactory). Each
484 Build is run on a single buildslave.
487 Status plugins, which deliver information about the build results
488 through protocols like HTTP, mail, and IRC.
492 @image{images/slavebuilder,,,SlaveBuilders,}
494 Each Builder is configured with a list of BuildSlaves that it will use
495 for its builds. These buildslaves are expected to behave identically:
496 the only reason to use multiple BuildSlaves for a single Builder is to
497 provide a measure of load-balancing.
499 Within a single BuildSlave, each Builder creates its own SlaveBuilder
500 instance. These SlaveBuilders operate independently from each other.
501 Each gets its own base directory to work in. It is quite common to
502 have many Builders sharing the same buildslave. For example, there
503 might be two buildslaves: one for i386, and a second for PowerPC.
504 There may then be a pair of Builders that do a full compile/test run,
505 one for each architecture, and a lone Builder that creates snapshot
506 source tarballs if the full builders complete successfully. The full
507 builders would each run on a single buildslave, whereas the tarball
508 creation step might run on either buildslave (since the platform
509 doesn't matter when creating source tarballs). In this case, the
510 mapping would look like:
513 Builder(full-i386) -> BuildSlaves(slave-i386)
514 Builder(full-ppc) -> BuildSlaves(slave-ppc)
515 Builder(source-tarball) -> BuildSlaves(slave-i386, slave-ppc)
518 and each BuildSlave would have two SlaveBuilders inside it, one for a
519 full builder, and a second for the source-tarball builder.
521 Once a SlaveBuilder is available, the Builder pulls one or more
522 BuildRequests off its incoming queue. (It may pull more than one if it
523 determines that it can merge the requests together; for example, there
524 may be multiple requests to build the current HEAD revision). These
525 requests are merged into a single Build instance, which includes the
526 SourceStamp that describes what exact version of the source code
527 should be used for the build. The Build is then randomly assigned to a
528 free SlaveBuilder and the build begins.
530 The behaviour when BuildRequests are merged can be customized, @pxref{Merging
533 @node Status Delivery Architecture, , Buildmaster Architecture, System Architecture
534 @subsection Status Delivery Architecture
536 The buildmaster maintains a central Status object, to which various
537 status plugins are connected. Through this Status object, a full
538 hierarchy of build status objects can be obtained.
540 @image{images/status,,,Status Delivery,}
542 The configuration file controls which status plugins are active. Each
543 status plugin gets a reference to the top-level Status object. From
544 there they can request information on each Builder, Build, Step, and
545 LogFile. This query-on-demand interface is used by the html.Waterfall
546 plugin to create the main status page each time a web browser hits the
549 The status plugins can also subscribe to hear about new Builds as they
550 occur: this is used by the MailNotifier to create new email messages
551 for each recently-completed Build.
553 The Status object records the status of old builds on disk in the
554 buildmaster's base directory. This allows it to return information
555 about historical builds.
557 There are also status objects that correspond to Schedulers and
558 BuildSlaves. These allow status plugins to report information about
559 upcoming builds, and the online/offline status of each buildslave.
562 @node Control Flow, , System Architecture, Introduction
563 @comment node-name, next, previous, up
564 @section Control Flow
566 A day in the life of the buildbot:
571 A developer commits some source code changes to the repository. A hook
572 script or commit trigger of some sort sends information about this
573 change to the buildmaster through one of its configured Change
574 Sources. This notification might arrive via email, or over a network
575 connection (either initiated by the buildmaster as it ``subscribes''
576 to changes, or by the commit trigger as it pushes Changes towards the
577 buildmaster). The Change contains information about who made the
578 change, what files were modified, which revision contains the change,
579 and any checkin comments.
582 The buildmaster distributes this change to all of its configured
583 Schedulers. Any ``important'' changes cause the ``tree-stable-timer''
584 to be started, and the Change is added to a list of those that will go
585 into a new Build. When the timer expires, a Build is started on each
586 of a set of configured Builders, all compiling/testing the same source
587 code. Unless configured otherwise, all Builds run in parallel on the
591 The Build consists of a series of Steps. Each Step causes some number
592 of commands to be invoked on the remote buildslave associated with
593 that Builder. The first step is almost always to perform a checkout of
594 the appropriate revision from the same VC system that produced the
595 Change. The rest generally perform a compile and run unit tests. As
596 each Step runs, the buildslave reports back command output and return
597 status to the buildmaster.
600 As the Build runs, status messages like ``Build Started'', ``Step
601 Started'', ``Build Finished'', etc, are published to a collection of
602 Status Targets. One of these targets is usually the HTML ``Waterfall''
603 display, which shows a chronological list of events, and summarizes
604 the results of the most recent build at the top of each column.
605 Developers can periodically check this page to see how their changes
606 have fared. If they see red, they know that they've made a mistake and
607 need to fix it. If they see green, they know that they've done their
608 duty and don't need to worry about their change breaking anything.
611 If a MailNotifier status target is active, the completion of a build
612 will cause email to be sent to any developers whose Changes were
613 incorporated into this Build. The MailNotifier can be configured to
614 only send mail upon failing builds, or for builds which have just
615 transitioned from passing to failing. Other status targets can provide
616 similar real-time notification via different communication channels,
622 @node Installation, Concepts, Introduction, Top
623 @chapter Installation
627 * Installing the code::
628 * Creating a buildmaster::
629 * Upgrading an Existing Buildmaster::
630 * Creating a buildslave::
631 * Launching the daemons::
638 @node Requirements, Installing the code, Installation, Installation
639 @section Requirements
641 At a bare minimum, you'll need the following (for both the buildmaster
646 Python: http://www.python.org
648 Buildbot requires python-2.3 or later, and is primarily developed
649 against python-2.4. It is also tested against python-2.5 .
652 Twisted: http://twistedmatrix.com
654 Both the buildmaster and the buildslaves require Twisted-2.0.x or
655 later. It has been tested against all releases of Twisted up to
656 Twisted-2.5.0 (the most recent as of this writing). As always, the
657 most recent version is recommended.
659 Twisted is delivered as a collection of subpackages. You'll need at
660 least "Twisted" (the core package), and you'll also want TwistedMail,
661 TwistedWeb, and TwistedWords (for sending email, serving a web status
662 page, and delivering build status via IRC, respectively). You might
663 also want TwistedConch (for the encrypted Manhole debug port). Note
664 that Twisted requires ZopeInterface to be installed as well.
668 Certain other packages may be useful on the system running the
673 CVSToys: http://purl.net/net/CVSToys
675 If your buildmaster uses FreshCVSSource to receive change notification
676 from a cvstoys daemon, it will require CVSToys be installed (tested
677 with CVSToys-1.0.10). If the it doesn't use that source (i.e. if you
678 only use a mail-parsing change source, or the SVN notification
679 script), you will not need CVSToys.
683 And of course, your project's build process will impose additional
684 requirements on the buildslaves. These hosts must have all the tools
685 necessary to compile and test your project's source code.
688 @node Installing the code, Creating a buildmaster, Requirements, Installation
689 @section Installing the code
693 The Buildbot is installed using the standard python @code{distutils}
694 module. After unpacking the tarball, the process is:
697 python setup.py build
698 python setup.py install
701 where the install step may need to be done as root. This will put the
702 bulk of the code in somewhere like
703 /usr/lib/python2.3/site-packages/buildbot . It will also install the
704 @code{buildbot} command-line tool in /usr/bin/buildbot.
706 To test this, shift to a different directory (like /tmp), and run:
712 If it shows you the versions of Buildbot and Twisted, the install went
713 ok. If it says @code{no such command} or it gets an @code{ImportError}
714 when it tries to load the libaries, then something went wrong.
715 @code{pydoc buildbot} is another useful diagnostic tool.
717 Windows users will find these files in other places. You will need to
718 make sure that python can find the libraries, and will probably find
719 it convenient to have @code{buildbot} on your PATH.
721 If you wish, you can run the buildbot unit test suite like this:
724 PYTHONPATH=. trial buildbot.test
727 This should run up to 192 tests, depending upon what VC tools you have
728 installed. On my desktop machine it takes about five minutes to
729 complete. Nothing should fail, a few might be skipped. If any of the
730 tests fail, you should stop and investigate the cause before
731 continuing the installation process, as it will probably be easier to
732 track down the bug early.
734 If you cannot or do not wish to install the buildbot into a site-wide
735 location like @file{/usr} or @file{/usr/local}, you can also install
736 it into the account's home directory. Do the install command like
740 python setup.py install --home=~
743 That will populate @file{~/lib/python} and create
744 @file{~/bin/buildbot}. Make sure this lib directory is on your
748 @node Creating a buildmaster, Upgrading an Existing Buildmaster, Installing the code, Installation
749 @section Creating a buildmaster
751 As you learned earlier (@pxref{System Architecture}), the buildmaster
752 runs on a central host (usually one that is publically visible, so
753 everybody can check on the status of the project), and controls all
754 aspects of the buildbot system. Let us call this host
755 @code{buildbot.example.org}.
757 You may wish to create a separate user account for the buildmaster,
758 perhaps named @code{buildmaster}. This can help keep your personal
759 configuration distinct from that of the buildmaster and is useful if
760 you have to use a mail-based notification system (@pxref{Change
761 Sources}). However, the Buildbot will work just fine with your regular
764 You need to choose a directory for the buildmaster, called the
765 @code{basedir}. This directory will be owned by the buildmaster, which
766 will use configuration files therein, and create status files as it
767 runs. @file{~/Buildbot} is a likely value. If you run multiple
768 buildmasters in the same account, or if you run both masters and
769 slaves, you may want a more distinctive name like
770 @file{~/Buildbot/master/gnomovision} or
771 @file{~/Buildmasters/fooproject}. If you are using a separate user
772 account, this might just be @file{~buildmaster/masters/fooproject}.
774 Once you've picked a directory, use the @command{buildbot
775 create-master} command to create the directory and populate it with
779 buildbot create-master @var{basedir}
782 You will need to create a configuration file (@pxref{Configuration})
783 before starting the buildmaster. Most of the rest of this manual is
784 dedicated to explaining how to do this. A sample configuration file is
785 placed in the working directory, named @file{master.cfg.sample}, which
786 can be copied to @file{master.cfg} and edited to suit your purposes.
788 (Internal details: This command creates a file named
789 @file{buildbot.tac} that contains all the state necessary to create
790 the buildmaster. Twisted has a tool called @code{twistd} which can use
791 this .tac file to create and launch a buildmaster instance. twistd
792 takes care of logging and daemonization (running the program in the
793 background). @file{/usr/bin/buildbot} is a front end which runs twistd
796 In addition to @file{buildbot.tac}, a small @file{Makefile.sample} is
797 installed. This can be used as the basis for customized daemon startup,
798 @xref{Launching the daemons}.
800 @node Upgrading an Existing Buildmaster, Creating a buildslave, Creating a buildmaster, Installation
801 @section Upgrading an Existing Buildmaster
803 If you have just installed a new version of the Buildbot code, and you
804 have buildmasters that were created using an older version, you'll
805 need to upgrade these buildmasters before you can use them. The
806 upgrade process adds and modifies files in the buildmaster's base
807 directory to make it compatible with the new code.
810 buildbot upgrade-master @var{basedir}
813 This command will also scan your @file{master.cfg} file for
814 incompatbilities (by loading it and printing any errors or deprecation
815 warnings that occur). Each buildbot release tries to be compatible
816 with configurations that worked cleanly (i.e. without deprecation
817 warnings) on the previous release: any functions or classes that are
818 to be removed will first be deprecated in a release, to give users a
819 chance to start using their replacement.
821 The 0.7.6 release introduced the @file{public_html/} directory, which
822 contains @file{index.html} and other files served by the
823 @code{WebStatus} and @code{Waterfall} status displays. The
824 @code{upgrade-master} command will create these files if they do not
825 already exist. It will not modify existing copies, but it will write a
826 new copy in e.g. @file{index.html.new} if the new version differs from
827 the version that already exists.
829 The @code{upgrade-master} command is idempotent. It is safe to run it
830 multiple times. After each upgrade of the buildbot code, you should
831 use @code{upgrade-master} on all your buildmasters.
834 @node Creating a buildslave, Launching the daemons, Upgrading an Existing Buildmaster, Installation
835 @section Creating a buildslave
837 Typically, you will be adding a buildslave to an existing buildmaster,
838 to provide additional architecture coverage. The buildbot
839 administrator will give you several pieces of information necessary to
840 connect to the buildmaster. You should also be somewhat familiar with
841 the project being tested, so you can troubleshoot build problems
844 The buildbot exists to make sure that the project's stated ``how to
845 build it'' process actually works. To this end, the buildslave should
846 run in an environment just like that of your regular developers.
847 Typically the project build process is documented somewhere
848 (@file{README}, @file{INSTALL}, etc), in a document that should
849 mention all library dependencies and contain a basic set of build
850 instructions. This document will be useful as you configure the host
851 and account in which the buildslave runs.
853 Here's a good checklist for setting up a buildslave:
859 It is recommended (although not mandatory) to set up a separate user
860 account for the buildslave. This account is frequently named
861 @code{buildbot} or @code{buildslave}. This serves to isolate your
862 personal working environment from that of the slave's, and helps to
863 minimize the security threat posed by letting possibly-unknown
864 contributors run arbitrary code on your system. The account should
865 have a minimum of fancy init scripts.
868 Install the buildbot code
870 Follow the instructions given earlier (@pxref{Installing the code}).
871 If you use a separate buildslave account, and you didn't install the
872 buildbot code to a shared location, then you will need to install it
873 with @code{--home=~} for each account that needs it.
878 Make sure the host can actually reach the buildmaster. Usually the
879 buildmaster is running a status webserver on the same machine, so
880 simply point your web browser at it and see if you can get there.
881 Install whatever additional packages or libraries the project's
882 INSTALL document advises. (or not: if your buildslave is supposed to
883 make sure that building without optional libraries still works, then
884 don't install those libraries).
886 Again, these libraries don't necessarily have to be installed to a
887 site-wide shared location, but they must be available to your build
888 process. Accomplishing this is usually very specific to the build
889 process, so installing them to @file{/usr} or @file{/usr/local} is
890 usually the best approach.
893 Test the build process
895 Follow the instructions in the INSTALL document, in the buildslave's
896 account. Perform a full CVS (or whatever) checkout, configure, make,
897 run tests, etc. Confirm that the build works without manual fussing.
898 If it doesn't work when you do it by hand, it will be unlikely to work
899 when the buildbot attempts to do it in an automated fashion.
902 Choose a base directory
904 This should be somewhere in the buildslave's account, typically named
905 after the project which is being tested. The buildslave will not touch
906 any file outside of this directory. Something like @file{~/Buildbot}
907 or @file{~/Buildslaves/fooproject} is appropriate.
910 Get the buildmaster host/port, botname, and password
912 When the buildbot admin configures the buildmaster to accept and use
913 your buildslave, they will provide you with the following pieces of
918 your buildslave's name
920 the password assigned to your buildslave
922 the hostname and port number of the buildmaster, i.e. buildbot.example.org:8007
926 Create the buildslave
928 Now run the 'buildbot' command as follows:
931 buildbot create-slave @var{BASEDIR} @var{MASTERHOST}:@var{PORT} @var{SLAVENAME} @var{PASSWORD}
934 This will create the base directory and a collection of files inside,
935 including the @file{buildbot.tac} file that contains all the
936 information you passed to the @code{buildbot} command.
939 Fill in the hostinfo files
941 When it first connects, the buildslave will send a few files up to the
942 buildmaster which describe the host that it is running on. These files
943 are presented on the web status display so that developers have more
944 information to reproduce any test failures that are witnessed by the
945 buildbot. There are sample files in the @file{info} subdirectory of
946 the buildbot's base directory. You should edit these to correctly
947 describe you and your host.
949 @file{BASEDIR/info/admin} should contain your name and email address.
950 This is the ``buildslave admin address'', and will be visible from the
951 build status page (so you may wish to munge it a bit if
952 address-harvesting spambots are a concern).
954 @file{BASEDIR/info/host} should be filled with a brief description of
955 the host: OS, version, memory size, CPU speed, versions of relevant
956 libraries installed, and finally the version of the buildbot code
957 which is running the buildslave.
959 If you run many buildslaves, you may want to create a single
960 @file{~buildslave/info} file and share it among all the buildslaves
966 * Buildslave Options::
969 @node Buildslave Options, , Creating a buildslave, Creating a buildslave
970 @subsection Buildslave Options
972 There are a handful of options you might want to use when creating the
973 buildslave with the @command{buildbot create-slave <options> DIR <params>}
974 command. You can type @command{buildbot create-slave --help} for a summary.
975 To use these, just include them on the @command{buildbot create-slave}
976 command line, like this:
979 buildbot create-slave --umask=022 ~/buildslave buildmaster.example.org:42012 myslavename mypasswd
984 This is a boolean flag that tells the buildslave whether to launch
985 child processes in a PTY (the default) or with regular pipes. The
986 advantage of using a PTY is that ``grandchild'' processes are more
987 likely to be cleaned up if the build is interrupted or times out
988 (since it enables the use of a ``process group'' in which all child
989 processes will be placed). The disadvantages: some forms of Unix have
990 problems with PTYs, some of your unit tests may behave differently
991 when run under a PTY (generally those which check to see if they are
992 being run interactively), and PTYs will merge the stdout and stderr
993 streams into a single output stream (which means the red-vs-black
994 coloring in the logfiles will be lost). If you encounter problems, you
995 can add @code{--usepty=0} to disable the use of PTYs. Note that
996 windows buildslaves never use PTYs.
999 This is a string (generally an octal representation of an integer)
1000 which will cause the buildslave process' ``umask'' value to be set
1001 shortly after initialization. The ``twistd'' daemonization utility
1002 forces the umask to 077 at startup (which means that all files created
1003 by the buildslave or its child processes will be unreadable by any
1004 user other than the buildslave account). If you want build products to
1005 be readable by other accounts, you can add @code{--umask=022} to tell
1006 the buildslave to fix the umask after twistd clobbers it. If you want
1007 build products to be @emph{writable} by other accounts too, use
1008 @code{--umask=000}, but this is likely to be a security problem.
1011 This is a number that indicates how frequently ``keepalive'' messages
1012 should be sent from the buildslave to the buildmaster, expressed in
1013 seconds. The default (600) causes a message to be sent to the
1014 buildmaster at least once every 10 minutes. To set this to a lower
1015 value, use e.g. @code{--keepalive=120}.
1017 If the buildslave is behind a NAT box or stateful firewall, these
1018 messages may help to keep the connection alive: some NAT boxes tend to
1019 forget about a connection if it has not been used in a while. When
1020 this happens, the buildmaster will think that the buildslave has
1021 disappeared, and builds will time out. Meanwhile the buildslave will
1022 not realize than anything is wrong.
1025 This is a number that indicates the maximum amount of time the
1026 buildslave will wait between connection attempts, expressed in
1027 seconds. The default (300) causes the buildslave to wait at most 5
1028 minutes before trying to connect to the buildmaster again.
1031 This is the size in bytes when to rotate the Twisted log files.
1034 This is the number of log rotations to keep around. You can either
1035 specify a number or @code{None} (the default) to keep all
1036 @file{twistd.log} files around.
1041 @node Launching the daemons, Logfiles, Creating a buildslave, Installation
1042 @section Launching the daemons
1044 Both the buildmaster and the buildslave run as daemon programs. To
1045 launch them, pass the working directory to the @code{buildbot}
1049 buildbot start @var{BASEDIR}
1052 This command will start the daemon and then return, so normally it
1053 will not produce any output. To verify that the programs are indeed
1054 running, look for a pair of files named @file{twistd.log} and
1055 @file{twistd.pid} that should be created in the working directory.
1056 @file{twistd.pid} contains the process ID of the newly-spawned daemon.
1058 When the buildslave connects to the buildmaster, new directories will
1059 start appearing in its base directory. The buildmaster tells the slave
1060 to create a directory for each Builder which will be using that slave.
1061 All build operations are performed within these directories: CVS
1062 checkouts, compiles, and tests.
1064 Once you get everything running, you will want to arrange for the
1065 buildbot daemons to be started at boot time. One way is to use
1066 @code{cron}, by putting them in a @@reboot crontab entry@footnote{this
1067 @@reboot syntax is understood by Vixie cron, which is the flavor
1068 usually provided with linux systems. Other unices may have a cron that
1069 doesn't understand @@reboot}:
1072 @@reboot buildbot start @var{BASEDIR}
1075 When you run @command{crontab} to set this up, remember to do it as
1076 the buildmaster or buildslave account! If you add this to your crontab
1077 when running as your regular account (or worse yet, root), then the
1078 daemon will run as the wrong user, quite possibly as one with more
1079 authority than you intended to provide.
1081 It is important to remember that the environment provided to cron jobs
1082 and init scripts can be quite different that your normal runtime.
1083 There may be fewer environment variables specified, and the PATH may
1084 be shorter than usual. It is a good idea to test out this method of
1085 launching the buildslave by using a cron job with a time in the near
1086 future, with the same command, and then check @file{twistd.log} to
1087 make sure the slave actually started correctly. Common problems here
1088 are for @file{/usr/local} or @file{~/bin} to not be on your
1089 @code{PATH}, or for @code{PYTHONPATH} to not be set correctly.
1090 Sometimes @code{HOME} is messed up too.
1092 To modify the way the daemons are started (perhaps you want to set
1093 some environment variables first, or perform some cleanup each time),
1094 you can create a file named @file{Makefile.buildbot} in the base
1095 directory. When the @file{buildbot} front-end tool is told to
1096 @command{start} the daemon, and it sees this file (and
1097 @file{/usr/bin/make} exists), it will do @command{make -f
1098 Makefile.buildbot start} instead of its usual action (which involves
1099 running @command{twistd}). When the buildmaster or buildslave is
1100 installed, a @file{Makefile.sample} is created which implements the
1101 same behavior as the the @file{buildbot} tool uses, so if you want to
1102 customize the process, just copy @file{Makefile.sample} to
1103 @file{Makefile.buildbot} and edit it as necessary.
1105 Some distributions may include conveniences to make starting buildbot
1106 at boot time easy. For instance, with the default buildbot package in
1107 Debian-based distributions, you may only need to modify
1108 @code{/etc/default/buildbot} (see also @code{/etc/init.d/buildbot}, which
1109 reads the configuration in @code{/etc/default/buildbot}).
1111 @node Logfiles, Shutdown, Launching the daemons, Installation
1116 While a buildbot daemon runs, it emits text to a logfile, named
1117 @file{twistd.log}. A command like @code{tail -f twistd.log} is useful
1118 to watch the command output as it runs.
1120 The buildmaster will announce any errors with its configuration file
1121 in the logfile, so it is a good idea to look at the log at startup
1122 time to check for any problems. Most buildmaster activities will cause
1123 lines to be added to the log.
1125 @node Shutdown, Maintenance, Logfiles, Installation
1128 To stop a buildmaster or buildslave manually, use:
1131 buildbot stop @var{BASEDIR}
1134 This simply looks for the @file{twistd.pid} file and kills whatever
1135 process is identified within.
1137 At system shutdown, all processes are sent a @code{SIGKILL}. The
1138 buildmaster and buildslave will respond to this by shutting down
1141 The buildmaster will respond to a @code{SIGHUP} by re-reading its
1142 config file. Of course, this only works on unix-like systems with
1143 signal support, and won't work on Windows. The following shortcut is
1147 buildbot reconfig @var{BASEDIR}
1150 When you update the Buildbot code to a new release, you will need to
1151 restart the buildmaster and/or buildslave before it can take advantage
1152 of the new code. You can do a @code{buildbot stop @var{BASEDIR}} and
1153 @code{buildbot start @var{BASEDIR}} in quick succession, or you can
1154 use the @code{restart} shortcut, which does both steps for you:
1157 buildbot restart @var{BASEDIR}
1160 There are certain configuration changes that are not handled cleanly
1161 by @code{buildbot reconfig}. If this occurs, @code{buildbot restart}
1162 is a more robust tool to fully switch over to the new configuration.
1164 @code{buildbot restart} may also be used to start a stopped Buildbot
1165 instance. This behaviour is useful when writing scripts that stop, start
1166 and restart Buildbot.
1168 A buildslave may also be gracefully shutdown from the
1169 @pxref{WebStatus} status plugin. This is useful to shutdown a
1170 buildslave without interrupting any current builds. The buildmaster
1171 will wait until the buildslave is finished all its current builds, and
1172 will then tell the buildslave to shutdown.
1174 @node Maintenance, Troubleshooting, Shutdown, Installation
1175 @section Maintenance
1177 It is a good idea to check the buildmaster's status page every once in
1178 a while, to see if your buildslave is still online. Eventually the
1179 buildbot will probably be enhanced to send you email (via the
1180 @file{info/admin} email address) when the slave has been offline for
1181 more than a few hours.
1183 If you find you can no longer provide a buildslave to the project, please
1184 let the project admins know, so they can put out a call for a
1187 The Buildbot records status and logs output continually, each time a
1188 build is performed. The status tends to be small, but the build logs
1189 can become quite large. Each build and log are recorded in a separate
1190 file, arranged hierarchically under the buildmaster's base directory.
1191 To prevent these files from growing without bound, you should
1192 periodically delete old build logs. A simple cron job to delete
1193 anything older than, say, two weeks should do the job. The only trick
1194 is to leave the @file{buildbot.tac} and other support files alone, for
1195 which find's @code{-mindepth} argument helps skip everything in the
1196 top directory. You can use something like the following:
1199 @@weekly cd BASEDIR && find . -mindepth 2 i-path './public_html/*' -prune -o -type f -mtime +14 -exec rm @{@} \;
1200 @@weekly cd BASEDIR && find twistd.log* -mtime +14 -exec rm @{@} \;
1203 @node Troubleshooting, , Maintenance, Installation
1204 @section Troubleshooting
1206 Here are a few hints on diagnosing common problems.
1209 * Starting the buildslave::
1210 * Connecting to the buildmaster::
1214 @node Starting the buildslave, Connecting to the buildmaster, Troubleshooting, Troubleshooting
1215 @subsection Starting the buildslave
1217 Cron jobs are typically run with a minimal shell (@file{/bin/sh}, not
1218 @file{/bin/bash}), and tilde expansion is not always performed in such
1219 commands. You may want to use explicit paths, because the @code{PATH}
1220 is usually quite short and doesn't include anything set by your
1221 shell's startup scripts (@file{.profile}, @file{.bashrc}, etc). If
1222 you've installed buildbot (or other python libraries) to an unusual
1223 location, you may need to add a @code{PYTHONPATH} specification (note
1224 that python will do tilde-expansion on @code{PYTHONPATH} elements by
1225 itself). Sometimes it is safer to fully-specify everything:
1228 @@reboot PYTHONPATH=~/lib/python /usr/local/bin/buildbot start /usr/home/buildbot/basedir
1231 Take the time to get the @@reboot job set up. Otherwise, things will work
1232 fine for a while, but the first power outage or system reboot you have will
1233 stop the buildslave with nothing but the cries of sorrowful developers to
1234 remind you that it has gone away.
1236 @node Connecting to the buildmaster, Forcing Builds, Starting the buildslave, Troubleshooting
1237 @subsection Connecting to the buildmaster
1239 If the buildslave cannot connect to the buildmaster, the reason should
1240 be described in the @file{twistd.log} logfile. Some common problems
1241 are an incorrect master hostname or port number, or a mistyped bot
1242 name or password. If the buildslave loses the connection to the
1243 master, it is supposed to attempt to reconnect with an
1244 exponentially-increasing backoff. Each attempt (and the time of the
1245 next attempt) will be logged. If you get impatient, just manually stop
1246 and re-start the buildslave.
1248 When the buildmaster is restarted, all slaves will be disconnected,
1249 and will attempt to reconnect as usual. The reconnect time will depend
1250 upon how long the buildmaster is offline (i.e. how far up the
1251 exponential backoff curve the slaves have travelled). Again,
1252 @code{buildbot stop @var{BASEDIR}; buildbot start @var{BASEDIR}} will
1253 speed up the process.
1255 @node Forcing Builds, , Connecting to the buildmaster, Troubleshooting
1256 @subsection Forcing Builds
1258 From the buildmaster's main status web page, you can force a build to
1259 be run on your build slave. Figure out which column is for a builder
1260 that runs on your slave, click on that builder's name, and the page
1261 that comes up will have a ``Force Build'' button. Fill in the form,
1262 hit the button, and a moment later you should see your slave's
1263 @file{twistd.log} filling with commands being run. Using @code{pstree}
1264 or @code{top} should also reveal the cvs/make/gcc/etc processes being
1265 run by the buildslave. Note that the same web page should also show
1266 the @file{admin} and @file{host} information files that you configured
1269 @node Concepts, Configuration, Installation, Top
1272 This chapter defines some of the basic concepts that the Buildbot
1273 uses. You'll need to understand how the Buildbot sees the world to
1274 configure it properly.
1277 * Version Control Systems::
1283 * Build Properties::
1286 @node Version Control Systems, Schedulers, Concepts, Concepts
1287 @section Version Control Systems
1289 @cindex Version Control
1291 These source trees come from a Version Control System of some kind.
1292 CVS and Subversion are two popular ones, but the Buildbot supports
1293 others. All VC systems have some notion of an upstream
1294 @code{repository} which acts as a server@footnote{except Darcs, but
1295 since the Buildbot never modifies its local source tree we can ignore
1296 the fact that Darcs uses a less centralized model}, from which clients
1297 can obtain source trees according to various parameters. The VC
1298 repository provides source trees of various projects, for different
1299 branches, and from various points in time. The first thing we have to
1300 do is to specify which source tree we want to get.
1303 * Generalizing VC Systems::
1304 * Source Tree Specifications::
1305 * How Different VC Systems Specify Sources::
1306 * Attributes of Changes::
1309 @node Generalizing VC Systems, Source Tree Specifications, Version Control Systems, Version Control Systems
1310 @subsection Generalizing VC Systems
1312 For the purposes of the Buildbot, we will try to generalize all VC
1313 systems as having repositories that each provide sources for a variety
1314 of projects. Each project is defined as a directory tree with source
1315 files. The individual files may each have revisions, but we ignore
1316 that and treat the project as a whole as having a set of revisions
1317 (CVS is really the only VC system still in widespread use that has
1318 per-file revisions.. everything modern has moved to atomic tree-wide
1319 changesets). Each time someone commits a change to the project, a new
1320 revision becomes available. These revisions can be described by a
1321 tuple with two items: the first is a branch tag, and the second is
1322 some kind of revision stamp or timestamp. Complex projects may have
1323 multiple branch tags, but there is always a default branch. The
1324 timestamp may be an actual timestamp (such as the -D option to CVS),
1325 or it may be a monotonically-increasing transaction number (such as
1326 the change number used by SVN and P4, or the revision number used by
1327 Arch/Baz/Bazaar, or a labeled tag used in CVS)@footnote{many VC
1328 systems provide more complexity than this: in particular the local
1329 views that P4 and ClearCase can assemble out of various source
1330 directories are more complex than we're prepared to take advantage of
1331 here}. The SHA1 revision ID used by Monotone, Mercurial, and Git is
1332 also a kind of revision stamp, in that it specifies a unique copy of
1333 the source tree, as does a Darcs ``context'' file.
1335 When we aren't intending to make any changes to the sources we check out
1336 (at least not any that need to be committed back upstream), there are two
1337 basic ways to use a VC system:
1341 Retrieve a specific set of source revisions: some tag or key is used
1342 to index this set, which is fixed and cannot be changed by subsequent
1343 developers committing new changes to the tree. Releases are built from
1344 tagged revisions like this, so that they can be rebuilt again later
1345 (probably with controlled modifications).
1347 Retrieve the latest sources along a specific branch: some tag is used
1348 to indicate which branch is to be used, but within that constraint we want
1349 to get the latest revisions.
1352 Build personnel or CM staff typically use the first approach: the
1353 build that results is (ideally) completely specified by the two
1354 parameters given to the VC system: repository and revision tag. This
1355 gives QA and end-users something concrete to point at when reporting
1356 bugs. Release engineers are also reportedly fond of shipping code that
1357 can be traced back to a concise revision tag of some sort.
1359 Developers are more likely to use the second approach: each morning
1360 the developer does an update to pull in the changes committed by the
1361 team over the last day. These builds are not easy to fully specify: it
1362 depends upon exactly when you did a checkout, and upon what local
1363 changes the developer has in their tree. Developers do not normally
1364 tag each build they produce, because there is usually significant
1365 overhead involved in creating these tags. Recreating the trees used by
1366 one of these builds can be a challenge. Some VC systems may provide
1367 implicit tags (like a revision number), while others may allow the use
1368 of timestamps to mean ``the state of the tree at time X'' as opposed
1369 to a tree-state that has been explicitly marked.
1371 The Buildbot is designed to help developers, so it usually works in
1372 terms of @emph{the latest} sources as opposed to specific tagged
1373 revisions. However, it would really prefer to build from reproducible
1374 source trees, so implicit revisions are used whenever possible.
1376 @node Source Tree Specifications, How Different VC Systems Specify Sources, Generalizing VC Systems, Version Control Systems
1377 @subsection Source Tree Specifications
1379 So for the Buildbot's purposes we treat each VC system as a server
1380 which can take a list of specifications as input and produce a source
1381 tree as output. Some of these specifications are static: they are
1382 attributes of the builder and do not change over time. Others are more
1383 variable: each build will have a different value. The repository is
1384 changed over time by a sequence of Changes, each of which represents a
1385 single developer making changes to some set of files. These Changes
1386 are cumulative@footnote{Monotone's @emph{multiple heads} feature
1387 violates this assumption of cumulative Changes, but in most situations
1388 the changes don't occur frequently enough for this to be a significant
1391 For normal builds, the Buildbot wants to get well-defined source trees
1392 that contain specific Changes, and exclude other Changes that may have
1393 occurred after the desired ones. We assume that the Changes arrive at
1394 the buildbot (through one of the mechanisms described in @pxref{Change
1395 Sources}) in the same order in which they are committed to the
1396 repository. The Buildbot waits for the tree to become ``stable''
1397 before initiating a build, for two reasons. The first is that
1398 developers frequently make multiple related commits in quick
1399 succession, even when the VC system provides ways to make atomic
1400 transactions involving multiple files at the same time. Running a
1401 build in the middle of these sets of changes would use an inconsistent
1402 set of source files, and is likely to fail (and is certain to be less
1403 useful than a build which uses the full set of changes). The
1404 tree-stable-timer is intended to avoid these useless builds that
1405 include some of the developer's changes but not all. The second reason
1406 is that some VC systems (i.e. CVS) do not provide repository-wide
1407 transaction numbers, so that timestamps are the only way to refer to
1408 a specific repository state. These timestamps may be somewhat
1409 ambiguous, due to processing and notification delays. By waiting until
1410 the tree has been stable for, say, 10 minutes, we can choose a
1411 timestamp from the middle of that period to use for our source
1412 checkout, and then be reasonably sure that any clock-skew errors will
1413 not cause the build to be performed on an inconsistent set of source
1416 The Schedulers always use the tree-stable-timer, with a timeout that
1417 is configured to reflect a reasonable tradeoff between build latency
1418 and change frequency. When the VC system provides coherent
1419 repository-wide revision markers (such as Subversion's revision
1420 numbers, or in fact anything other than CVS's timestamps), the
1421 resulting Build is simply performed against a source tree defined by
1422 that revision marker. When the VC system does not provide this, a
1423 timestamp from the middle of the tree-stable period is used to
1424 generate the source tree@footnote{this @code{checkoutDelay} defaults
1425 to half the tree-stable timer, but it can be overridden with an
1426 argument to the Source Step}.
1428 @node How Different VC Systems Specify Sources, Attributes of Changes, Source Tree Specifications, Version Control Systems
1429 @subsection How Different VC Systems Specify Sources
1431 For CVS, the static specifications are @code{repository} and
1432 @code{module}. In addition to those, each build uses a timestamp (or
1433 omits the timestamp to mean @code{the latest}) and @code{branch tag}
1434 (which defaults to HEAD). These parameters collectively specify a set
1435 of sources from which a build may be performed.
1437 @uref{http://subversion.tigris.org, Subversion} combines the
1438 repository, module, and branch into a single @code{Subversion URL}
1439 parameter. Within that scope, source checkouts can be specified by a
1440 numeric @code{revision number} (a repository-wide
1441 monotonically-increasing marker, such that each transaction that
1442 changes the repository is indexed by a different revision number), or
1443 a revision timestamp. When branches are used, the repository and
1444 module form a static @code{baseURL}, while each build has a
1445 @code{revision number} and a @code{branch} (which defaults to a
1446 statically-specified @code{defaultBranch}). The @code{baseURL} and
1447 @code{branch} are simply concatenated together to derive the
1448 @code{svnurl} to use for the checkout.
1450 @uref{http://www.perforce.com/, Perforce} is similar. The server
1451 is specified through a @code{P4PORT} parameter. Module and branch
1452 are specified in a single depot path, and revisions are
1453 depot-wide. When branches are used, the @code{p4base} and
1454 @code{defaultBranch} are concatenated together to produce the depot
1457 @uref{http://wiki.gnuarch.org/, Arch} and
1458 @uref{http://bazaar.canonical.com/, Bazaar} specify a repository by
1459 URL, as well as a @code{version} which is kind of like a branch name.
1460 Arch uses the word @code{archive} to represent the repository. Arch
1461 lets you push changes from one archive to another, removing the strict
1462 centralization required by CVS and SVN. It retains the distinction
1463 between repository and working directory that most other VC systems
1464 use. For complex multi-module directory structures, Arch has a
1465 built-in @code{build config} layer with which the checkout process has
1466 two steps. First, an initial bootstrap checkout is performed to
1467 retrieve a set of build-config files. Second, one of these files is
1468 used to figure out which archives/modules should be used to populate
1469 subdirectories of the initial checkout.
1471 Builders which use Arch and Bazaar therefore have a static archive
1472 @code{url}, and a default ``branch'' (which is a string that specifies
1473 a complete category--branch--version triple). Each build can have its
1474 own branch (the category--branch--version string) to override the
1475 default, as well as a revision number (which is turned into a
1476 --patch-NN suffix when performing the checkout).
1479 @uref{http://bazaar-vcs.org, Bzr} (which is a descendant of
1480 Arch/Bazaar, and is frequently referred to as ``Bazaar'') has the same
1481 sort of repository-vs-workspace model as Arch, but the repository data
1482 can either be stored inside the working directory or kept elsewhere
1483 (either on the same machine or on an entirely different machine). For
1484 the purposes of Buildbot (which never commits changes), the repository
1485 is specified with a URL and a revision number.
1487 The most common way to obtain read-only access to a bzr tree is via
1488 HTTP, simply by making the repository visible through a web server
1489 like Apache. Bzr can also use FTP and SFTP servers, if the buildslave
1490 process has sufficient privileges to access them. Higher performance
1491 can be obtained by running a special Bazaar-specific server. None of
1492 these matter to the buildbot: the repository URL just has to match the
1493 kind of server being used. The @code{repoURL} argument provides the
1494 location of the repository.
1496 Branches are expressed as subdirectories of the main central
1497 repository, which means that if branches are being used, the BZR step
1498 is given a @code{baseURL} and @code{defaultBranch} instead of getting
1499 the @code{repoURL} argument.
1502 @uref{http://darcs.net/, Darcs} doesn't really have the
1503 notion of a single master repository. Nor does it really have
1504 branches. In Darcs, each working directory is also a repository, and
1505 there are operations to push and pull patches from one of these
1506 @code{repositories} to another. For the Buildbot's purposes, all you
1507 need to do is specify the URL of a repository that you want to build
1508 from. The build slave will then pull the latest patches from that
1509 repository and build them. Multiple branches are implemented by using
1510 multiple repositories (possibly living on the same server).
1512 Builders which use Darcs therefore have a static @code{repourl} which
1513 specifies the location of the repository. If branches are being used,
1514 the source Step is instead configured with a @code{baseURL} and a
1515 @code{defaultBranch}, and the two strings are simply concatenated
1516 together to obtain the repository's URL. Each build then has a
1517 specific branch which replaces @code{defaultBranch}, or just uses the
1518 default one. Instead of a revision number, each build can have a
1519 ``context'', which is a string that records all the patches that are
1520 present in a given tree (this is the output of @command{darcs changes
1521 --context}, and is considerably less concise than, e.g. Subversion's
1522 revision number, but the patch-reordering flexibility of Darcs makes
1523 it impossible to provide a shorter useful specification).
1525 @uref{http://selenic.com/mercurial, Mercurial} is like Darcs, in that
1526 each branch is stored in a separate repository. The @code{repourl},
1527 @code{baseURL}, and @code{defaultBranch} arguments are all handled the
1528 same way as with Darcs. The ``revision'', however, is the hash
1529 identifier returned by @command{hg identify}.
1531 @uref{http://git.or.cz/, Git} also follows a decentralized model, and
1532 each repository can have several branches and tags. The source Step is
1533 configured with a static @code{repourl} which specifies the location
1534 of the repository. In addition, an optional @code{branch} parameter
1535 can be specified to check out code from a specific branch instead of
1536 the default ``master'' branch. The ``revision'' is specified as a SHA1
1537 hash as returned by e.g. @command{git rev-parse}. No attempt is made
1538 to ensure that the specified revision is actually a subset of the
1542 @node Attributes of Changes, , How Different VC Systems Specify Sources, Version Control Systems
1543 @subsection Attributes of Changes
1547 Each Change has a @code{who} attribute, which specifies which
1548 developer is responsible for the change. This is a string which comes
1549 from a namespace controlled by the VC repository. Frequently this
1550 means it is a username on the host which runs the repository, but not
1551 all VC systems require this (Arch, for example, uses a fully-qualified
1552 @code{Arch ID}, which looks like an email address, as does Darcs).
1553 Each StatusNotifier will map the @code{who} attribute into something
1554 appropriate for their particular means of communication: an email
1555 address, an IRC handle, etc.
1559 It also has a list of @code{files}, which are just the tree-relative
1560 filenames of any files that were added, deleted, or modified for this
1561 Change. These filenames are used by the @code{fileIsImportant}
1562 function (in the Scheduler) to decide whether it is worth triggering a
1563 new build or not, e.g. the function could use the following function
1564 to only run a build if a C file were checked in:
1567 def has_C_files(change):
1568 for name in change.files:
1569 if name.endswith(".c"):
1574 Certain BuildSteps can also use the list of changed files
1575 to run a more targeted series of tests, e.g. the
1576 @code{python_twisted.Trial} step can run just the unit tests that
1577 provide coverage for the modified .py files instead of running the
1582 The Change also has a @code{comments} attribute, which is a string
1583 containing any checkin comments.
1587 Each Change can have a @code{revision} attribute, which describes how
1588 to get a tree with a specific state: a tree which includes this Change
1589 (and all that came before it) but none that come after it. If this
1590 information is unavailable, the @code{.revision} attribute will be
1591 @code{None}. These revisions are provided by the ChangeSource, and
1592 consumed by the @code{computeSourceRevision} method in the appropriate
1593 @code{step.Source} class.
1597 @code{revision} is an int, seconds since the epoch
1599 @code{revision} is an int, the changeset number (r%d)
1601 @code{revision} is a large string, the output of @code{darcs changes --context}
1603 @code{revision} is a short string (a hash ID), the output of @code{hg identify}
1605 @code{revision} is the full revision ID (ending in --patch-%d)
1607 @code{revision} is an int, the transaction number
1609 @code{revision} is a short string (a SHA1 hash), the output of e.g.
1610 @code{git rev-parse}
1615 The Change might also have a @code{branch} attribute. This indicates
1616 that all of the Change's files are in the same named branch. The
1617 Schedulers get to decide whether the branch should be built or not.
1619 For VC systems like CVS, Arch, Monotone, and Git, the @code{branch}
1620 name is unrelated to the filename. (that is, the branch name and the
1621 filename inhabit unrelated namespaces). For SVN, branches are
1622 expressed as subdirectories of the repository, so the file's
1623 ``svnurl'' is a combination of some base URL, the branch name, and the
1624 filename within the branch. (In a sense, the branch name and the
1625 filename inhabit the same namespace). Darcs branches are
1626 subdirectories of a base URL just like SVN. Mercurial branches are the
1631 branch='warner-newfeature', files=['src/foo.c']
1633 branch='branches/warner-newfeature', files=['src/foo.c']
1635 branch='warner-newfeature', files=['src/foo.c']
1637 branch='warner-newfeature', files=['src/foo.c']
1639 branch='buildbot--usebranches--0', files=['buildbot/master.py']
1641 branch='warner-newfeature', files=['src/foo.c']
1646 @c TODO: who is using 'links'? how is it being used?
1648 Finally, the Change might have a @code{links} list, which is intended
1649 to provide a list of URLs to a @emph{viewcvs}-style web page that
1650 provides more detail for this Change, perhaps including the full file
1654 @node Schedulers, BuildSet, Version Control Systems, Concepts
1659 Each Buildmaster has a set of @code{Scheduler} objects, each of which
1660 gets a copy of every incoming Change. The Schedulers are responsible
1661 for deciding when Builds should be run. Some Buildbot installations
1662 might have a single Scheduler, while others may have several, each for
1663 a different purpose.
1665 For example, a ``quick'' scheduler might exist to give immediate
1666 feedback to developers, hoping to catch obvious problems in the code
1667 that can be detected quickly. These typically do not run the full test
1668 suite, nor do they run on a wide variety of platforms. They also
1669 usually do a VC update rather than performing a brand-new checkout
1670 each time. You could have a ``quick'' scheduler which used a 30 second
1671 timeout, and feeds a single ``quick'' Builder that uses a VC
1672 @code{mode='update'} setting.
1674 A separate ``full'' scheduler would run more comprehensive tests a
1675 little while later, to catch more subtle problems. This scheduler
1676 would have a longer tree-stable-timer, maybe 30 minutes, and would
1677 feed multiple Builders (with a @code{mode=} of @code{'copy'},
1678 @code{'clobber'}, or @code{'export'}).
1680 The @code{tree-stable-timer} and @code{fileIsImportant} decisions are
1681 made by the Scheduler. Dependencies are also implemented here.
1682 Periodic builds (those which are run every N seconds rather than after
1683 new Changes arrive) are triggered by a special @code{Periodic}
1684 Scheduler subclass. The default Scheduler class can also be told to
1685 watch for specific branches, ignoring Changes on other branches. This
1686 may be useful if you have a trunk and a few release branches which
1687 should be tracked, but when you don't want to have the Buildbot pay
1688 attention to several dozen private user branches.
1690 When the setup has multiple sources of Changes the @code{category}
1691 can be used for @code{Scheduler} objects to filter out a subset
1692 of the Changes. Note that not all change sources can attach a category.
1694 Some Schedulers may trigger builds for other reasons, other than
1695 recent Changes. For example, a Scheduler subclass could connect to a
1696 remote buildmaster and watch for builds of a library to succeed before
1697 triggering a local build that uses that library.
1699 Each Scheduler creates and submits @code{BuildSet} objects to the
1700 @code{BuildMaster}, which is then responsible for making sure the
1701 individual @code{BuildRequests} are delivered to the target
1704 @code{Scheduler} instances are activated by placing them in the
1705 @code{c['schedulers']} list in the buildmaster config file. Each
1706 Scheduler has a unique name.
1709 @node BuildSet, BuildRequest, Schedulers, Concepts
1714 A @code{BuildSet} is the name given to a set of Builds that all
1715 compile/test the same version of the tree on multiple Builders. In
1716 general, all these component Builds will perform the same sequence of
1717 Steps, using the same source code, but on different platforms or
1718 against a different set of libraries.
1720 The @code{BuildSet} is tracked as a single unit, which fails if any of
1721 the component Builds have failed, and therefore can succeed only if
1722 @emph{all} of the component Builds have succeeded. There are two kinds
1723 of status notification messages that can be emitted for a BuildSet:
1724 the @code{firstFailure} type (which fires as soon as we know the
1725 BuildSet will fail), and the @code{Finished} type (which fires once
1726 the BuildSet has completely finished, regardless of whether the
1727 overall set passed or failed).
1729 A @code{BuildSet} is created with a @emph{source stamp} tuple of
1730 (branch, revision, changes, patch), some of which may be None, and a
1731 list of Builders on which it is to be run. They are then given to the
1732 BuildMaster, which is responsible for creating a separate
1733 @code{BuildRequest} for each Builder.
1735 There are a couple of different likely values for the
1739 @item (revision=None, changes=[CHANGES], patch=None)
1740 This is a @code{SourceStamp} used when a series of Changes have
1741 triggered a build. The VC step will attempt to check out a tree that
1742 contains CHANGES (and any changes that occurred before CHANGES, but
1743 not any that occurred after them).
1745 @item (revision=None, changes=None, patch=None)
1746 This builds the most recent code on the default branch. This is the
1747 sort of @code{SourceStamp} that would be used on a Build that was
1748 triggered by a user request, or a Periodic scheduler. It is also
1749 possible to configure the VC Source Step to always check out the
1750 latest sources rather than paying attention to the Changes in the
1751 SourceStamp, which will result in same behavior as this.
1753 @item (branch=BRANCH, revision=None, changes=None, patch=None)
1754 This builds the most recent code on the given BRANCH. Again, this is
1755 generally triggered by a user request or Periodic build.
1757 @item (revision=REV, changes=None, patch=(LEVEL, DIFF))
1758 This checks out the tree at the given revision REV, then applies a
1759 patch (using @code{patch -pLEVEL <DIFF}). The @ref{try} feature uses
1760 this kind of @code{SourceStamp}. If @code{patch} is None, the patching
1765 The buildmaster is responsible for turning the @code{BuildSet} into a
1766 set of @code{BuildRequest} objects and queueing them on the
1767 appropriate Builders.
1770 @node BuildRequest, Builder, BuildSet, Concepts
1771 @section BuildRequest
1773 @cindex BuildRequest
1775 A @code{BuildRequest} is a request to build a specific set of sources
1776 on a single specific @code{Builder}. Each @code{Builder} runs the
1777 @code{BuildRequest} as soon as it can (i.e. when an associated
1778 buildslave becomes free). @code{BuildRequest}s are prioritized from
1779 oldest to newest, so when a buildslave becomes free, the
1780 @code{Builder} with the oldest @code{BuildRequest} is run.
1782 The @code{BuildRequest} contains the @code{SourceStamp} specification.
1783 The actual process of running the build (the series of Steps that will
1784 be executed) is implemented by the @code{Build} object. In this future
1785 this might be changed, to have the @code{Build} define @emph{what}
1786 gets built, and a separate @code{BuildProcess} (provided by the
1787 Builder) to define @emph{how} it gets built.
1789 @code{BuildRequest} is created with optional @code{Properties}. One
1790 of these, @code{owner}, is collected by the resultant @code{Build} and
1791 added to the set of @emph{interested users} to which status
1792 notifications will be sent, depending on the configuration for each
1795 The @code{BuildRequest} may be mergeable with other compatible
1796 @code{BuildRequest}s. Builds that are triggered by incoming Changes
1797 will generally be mergeable. Builds that are triggered by user
1798 requests are generally not, unless they are multiple requests to build
1799 the @emph{latest sources} of the same branch.
1801 @node Builder, Users, BuildRequest, Concepts
1806 The @code{Builder} is a long-lived object which controls all Builds of
1807 a given type. Each one is created when the config file is first
1808 parsed, and lives forever (or rather until it is removed from the
1809 config file). It mediates the connections to the buildslaves that do
1810 all the work, and is responsible for creating the @code{Build} objects
1811 that decide @emph{how} a build is performed (i.e., which steps are
1812 executed in what order).
1814 Each @code{Builder} gets a unique name, and the path name of a
1815 directory where it gets to do all its work (there is a
1816 buildmaster-side directory for keeping status information, as well as
1817 a buildslave-side directory where the actual checkout/compile/test
1818 commands are executed). It also gets a @code{BuildFactory}, which is
1819 responsible for creating new @code{Build} instances: because the
1820 @code{Build} instance is what actually performs each build, choosing
1821 the @code{BuildFactory} is the way to specify what happens each time a
1824 Each @code{Builder} is associated with one of more @code{BuildSlaves}.
1825 A @code{Builder} which is used to perform OS-X builds (as opposed to
1826 Linux or Solaris builds) should naturally be associated with an
1827 OS-X-based buildslave.
1829 A @code{Builder} may be given a set of environment variables to be used
1830 in its @pxref{ShellCommand}s. These variables will override anything in the
1831 buildslave's environment. Variables passed directly to a ShellCommand will
1832 override variables of the same name passed to the Builder.
1834 For example, if you a pool of identical slaves it is often easier to manage
1835 variables like PATH from Buildbot rather than manually editing it inside of
1836 the slaves' environment.
1839 f = factory.BuildFactory
1840 f.addStep(ShellCommand(
1841 command=['bash', './configure']))
1842 f.addStep(Compile())
1845 @{'name': 'test', 'slavenames': ['slave1', 'slave2', 'slave3', 'slave4',
1846 'slave5', 'slave6'],
1847 'builddir': 'test', 'factory': f',
1848 'env': @{'PATH': '/opt/local/bin:/opt/app/bin:/usr/local/bin:/usr/bin'@}@}
1852 @node Users, Build Properties, Builder, Concepts
1857 Buildbot has a somewhat limited awareness of @emph{users}. It assumes
1858 the world consists of a set of developers, each of whom can be
1859 described by a couple of simple attributes. These developers make
1860 changes to the source code, causing builds which may succeed or fail.
1862 Each developer is primarily known through the source control system. Each
1863 Change object that arrives is tagged with a @code{who} field that
1864 typically gives the account name (on the repository machine) of the user
1865 responsible for that change. This string is the primary key by which the
1866 User is known, and is displayed on the HTML status pages and in each Build's
1869 To do more with the User than just refer to them, this username needs to
1870 be mapped into an address of some sort. The responsibility for this mapping
1871 is left up to the status module which needs the address. The core code knows
1872 nothing about email addresses or IRC nicknames, just user names.
1875 * Doing Things With Users::
1878 * Live Status Clients::
1881 @node Doing Things With Users, Email Addresses, Users, Users
1882 @subsection Doing Things With Users
1884 Each Change has a single User who is responsible for that Change. Most
1885 Builds have a set of Changes: the Build represents the first time these
1886 Changes have been built and tested by the Buildbot. The build has a
1887 ``blamelist'' that consists of a simple union of the Users responsible
1888 for all the Build's Changes.
1890 The Build provides (through the IBuildStatus interface) a list of Users
1891 who are ``involved'' in the build. For now this is equal to the
1892 blamelist, but in the future it will be expanded to include a ``build
1893 sheriff'' (a person who is ``on duty'' at that time and responsible for
1894 watching over all builds that occur during their shift), as well as
1895 per-module owners who simply want to keep watch over their domain (chosen by
1896 subdirectory or a regexp matched against the filenames pulled out of the
1897 Changes). The Involved Users are those who probably have an interest in the
1898 results of any given build.
1900 In the future, Buildbot will acquire the concept of ``Problems'',
1901 which last longer than builds and have beginnings and ends. For example, a
1902 test case which passed in one build and then failed in the next is a
1903 Problem. The Problem lasts until the test case starts passing again, at
1904 which point the Problem is said to be ``resolved''.
1906 If there appears to be a code change that went into the tree at the
1907 same time as the test started failing, that Change is marked as being
1908 resposible for the Problem, and the user who made the change is added
1909 to the Problem's ``Guilty'' list. In addition to this user, there may
1910 be others who share responsibility for the Problem (module owners,
1911 sponsoring developers). In addition to the Responsible Users, there
1912 may be a set of Interested Users, who take an interest in the fate of
1915 Problems therefore have sets of Users who may want to be kept aware of
1916 the condition of the problem as it changes over time. If configured, the
1917 Buildbot can pester everyone on the Responsible list with increasing
1918 harshness until the problem is resolved, with the most harshness reserved
1919 for the Guilty parties themselves. The Interested Users may merely be told
1920 when the problem starts and stops, as they are not actually responsible for
1923 @node Email Addresses, IRC Nicknames, Doing Things With Users, Users
1924 @subsection Email Addresses
1926 The @code{buildbot.status.mail.MailNotifier} class
1927 (@pxref{MailNotifier}) provides a status target which can send email
1928 about the results of each build. It accepts a static list of email
1929 addresses to which each message should be delivered, but it can also
1930 be configured to send mail to the Build's Interested Users. To do
1931 this, it needs a way to convert User names into email addresses.
1933 For many VC systems, the User Name is actually an account name on the
1934 system which hosts the repository. As such, turning the name into an
1935 email address is a simple matter of appending
1936 ``@@repositoryhost.com''. Some projects use other kinds of mappings
1937 (for example the preferred email address may be at ``project.org''
1938 despite the repository host being named ``cvs.project.org''), and some
1939 VC systems have full separation between the concept of a user and that
1940 of an account on the repository host (like Perforce). Some systems
1941 (like Arch) put a full contact email address in every change.
1943 To convert these names to addresses, the MailNotifier uses an EmailLookup
1944 object. This provides a .getAddress method which accepts a name and
1945 (eventually) returns an address. The default @code{MailNotifier}
1946 module provides an EmailLookup which simply appends a static string,
1947 configurable when the notifier is created. To create more complex behaviors
1948 (perhaps using an LDAP lookup, or using ``finger'' on a central host to
1949 determine a preferred address for the developer), provide a different object
1950 as the @code{lookup} argument.
1952 In the future, when the Problem mechanism has been set up, the Buildbot
1953 will need to send mail to arbitrary Users. It will do this by locating a
1954 MailNotifier-like object among all the buildmaster's status targets, and
1955 asking it to send messages to various Users. This means the User-to-address
1956 mapping only has to be set up once, in your MailNotifier, and every email
1957 message the buildbot emits will take advantage of it.
1959 @node IRC Nicknames, Live Status Clients, Email Addresses, Users
1960 @subsection IRC Nicknames
1962 Like MailNotifier, the @code{buildbot.status.words.IRC} class
1963 provides a status target which can announce the results of each build. It
1964 also provides an interactive interface by responding to online queries
1965 posted in the channel or sent as private messages.
1967 In the future, the buildbot can be configured map User names to IRC
1968 nicknames, to watch for the recent presence of these nicknames, and to
1969 deliver build status messages to the interested parties. Like
1970 @code{MailNotifier} does for email addresses, the @code{IRC} object
1971 will have an @code{IRCLookup} which is responsible for nicknames. The
1972 mapping can be set up statically, or it can be updated by online users
1973 themselves (by claiming a username with some kind of ``buildbot: i am
1974 user warner'' commands).
1976 Once the mapping is established, the rest of the buildbot can ask the
1977 @code{IRC} object to send messages to various users. It can report on
1978 the likelihood that the user saw the given message (based upon how long the
1979 user has been inactive on the channel), which might prompt the Problem
1980 Hassler logic to send them an email message instead.
1982 @node Live Status Clients, , IRC Nicknames, Users
1983 @subsection Live Status Clients
1985 The Buildbot also offers a PB-based status client interface which can
1986 display real-time build status in a GUI panel on the developer's desktop.
1987 This interface is normally anonymous, but it could be configured to let the
1988 buildmaster know @emph{which} developer is using the status client. The
1989 status client could then be used as a message-delivery service, providing an
1990 alternative way to deliver low-latency high-interruption messages to the
1991 developer (like ``hey, you broke the build'').
1993 @node Build Properties, , Users, Concepts
1994 @section Build Properties
1997 Each build has a set of ``Build Properties'', which can be used by its
1998 BuildStep to modify their actions. These properties, in the form of
1999 key-value pairs, provide a general framework for dynamically altering
2000 the behavior of a build based on its circumstances.
2002 Properties come from a number of places:
2004 @item global configuration --
2005 These properties apply to all builds.
2007 A scheduler can specify properties available to all the builds it
2009 @item buildslaves --
2010 A buildslave can pass properties on to the builds it performs.
2012 A build automatically sets a number of properties on itself.
2014 Steps of a build can set properties that are available to subsequent
2015 steps. In particular, source steps set a number of properties.
2018 Properties are very flexible, and can be used to implement all manner
2019 of functionality. Here are some examples:
2021 Most Source steps record the revision that they checked out in
2022 the @code{got_revision} property. A later step could use this
2023 property to specify the name of a fully-built tarball, dropped in an
2024 easily-acessible directory for later testing.
2026 Some projects want to perform nightly builds as well as in response
2027 to committed changes. Such a project would run two schedulers,
2028 both pointing to the same set of builders, but could provide an
2029 @code{is_nightly} property so that steps can distinguish the nightly
2030 builds, perhaps to run more resource-intensive tests.
2032 Some projects have different build processes on different systems.
2033 Rather than create a build factory for each slave, the steps can use
2034 buildslave properties to identify the unique aspects of each slave
2035 and adapt the build process dynamically.
2037 @node Configuration, Getting Source Code Changes, Concepts, Top
2038 @chapter Configuration
2040 @cindex Configuration
2042 The buildbot's behavior is defined by the ``config file'', which
2043 normally lives in the @file{master.cfg} file in the buildmaster's base
2044 directory (but this can be changed with an option to the
2045 @code{buildbot create-master} command). This file completely specifies
2046 which Builders are to be run, which slaves they should use, how
2047 Changes should be tracked, and where the status information is to be
2048 sent. The buildmaster's @file{buildbot.tac} file names the base
2049 directory; everything else comes from the config file.
2051 A sample config file was installed for you when you created the
2052 buildmaster, but you will need to edit it before your buildbot will do
2055 This chapter gives an overview of the format of this file and the
2056 various sections in it. You will need to read the later chapters to
2057 understand how to fill in each section properly.
2060 * Config File Format::
2061 * Loading the Config File::
2062 * Testing the Config File::
2063 * Defining the Project::
2064 * Change Sources and Schedulers::
2065 * Merging BuildRequests::
2066 * Setting the slaveport::
2067 * Buildslave Specifiers::
2068 * On-Demand ("Latent") Buildslaves::
2069 * Defining Global Properties::
2070 * Defining Builders::
2071 * Defining Status Targets::
2075 @node Config File Format, Loading the Config File, Configuration, Configuration
2076 @section Config File Format
2078 The config file is, fundamentally, just a piece of Python code which
2079 defines a dictionary named @code{BuildmasterConfig}, with a number of
2080 keys that are treated specially. You don't need to know Python to do
2081 basic configuration, though, you can just copy the syntax of the
2082 sample file. If you @emph{are} comfortable writing Python code,
2083 however, you can use all the power of a full programming language to
2084 achieve more complicated configurations.
2086 The @code{BuildmasterConfig} name is the only one which matters: all
2087 other names defined during the execution of the file are discarded.
2088 When parsing the config file, the Buildmaster generally compares the
2089 old configuration with the new one and performs the minimum set of
2090 actions necessary to bring the buildbot up to date: Builders which are
2091 not changed are left untouched, and Builders which are modified get to
2092 keep their old event history.
2094 Basic Python syntax: comments start with a hash character (``#''),
2095 tuples are defined with @code{(parenthesis, pairs)}, arrays are
2096 defined with @code{[square, brackets]}, tuples and arrays are mostly
2097 interchangeable. Dictionaries (data structures which map ``keys'' to
2098 ``values'') are defined with curly braces: @code{@{'key1': 'value1',
2099 'key2': 'value2'@} }. Function calls (and object instantiation) can use
2100 named parameters, like @code{w = html.Waterfall(http_port=8010)}.
2102 The config file starts with a series of @code{import} statements,
2103 which make various kinds of Steps and Status targets available for
2104 later use. The main @code{BuildmasterConfig} dictionary is created,
2105 then it is populated with a variety of keys. These keys are broken
2106 roughly into the following sections, each of which is documented in
2107 the rest of this chapter:
2113 Change Sources / Schedulers
2117 Buildslave Configuration
2119 Builders / Interlocks
2126 The config file can use a few names which are placed into its namespace:
2130 the base directory for the buildmaster. This string has not been
2131 expanded, so it may start with a tilde. It needs to be expanded before
2132 use. The config file is located in
2133 @code{os.path.expanduser(os.path.join(basedir, 'master.cfg'))}
2138 @node Loading the Config File, Testing the Config File, Config File Format, Configuration
2139 @section Loading the Config File
2141 The config file is only read at specific points in time. It is first
2142 read when the buildmaster is launched. Once it is running, there are
2143 various ways to ask it to reload the config file. If you are on the
2144 system hosting the buildmaster, you can send a @code{SIGHUP} signal to
2145 it: the @command{buildbot} tool has a shortcut for this:
2148 buildbot reconfig @var{BASEDIR}
2151 This command will show you all of the lines from @file{twistd.log}
2152 that relate to the reconfiguration. If there are any problems during
2153 the config-file reload, they will be displayed in these lines.
2155 The debug tool (@code{buildbot debugclient --master HOST:PORT}) has a
2156 ``Reload .cfg'' button which will also trigger a reload. In the
2157 future, there will be other ways to accomplish this step (probably a
2158 password-protected button on the web page, as well as a privileged IRC
2161 When reloading the config file, the buildmaster will endeavor to
2162 change as little as possible about the running system. For example,
2163 although old status targets may be shut down and new ones started up,
2164 any status targets that were not changed since the last time the
2165 config file was read will be left running and untouched. Likewise any
2166 Builders which have not been changed will be left running. If a
2167 Builder is modified (say, the build process is changed) while a Build
2168 is currently running, that Build will keep running with the old
2169 process until it completes. Any previously queued Builds (or Builds
2170 which get queued after the reconfig) will use the new process.
2172 @node Testing the Config File, Defining the Project, Loading the Config File, Configuration
2173 @section Testing the Config File
2175 To verify that the config file is well-formed and contains no
2176 deprecated or invalid elements, use the ``checkconfig'' command:
2179 % buildbot checkconfig master.cfg
2180 Config file is good!
2183 If the config file has deprecated features (perhaps because you've
2184 upgraded the buildmaster and need to update the config file to match),
2185 they will be announced by checkconfig. In this case, the config file
2186 will work, but you should really remove the deprecated items and use
2187 the recommended replacements instead:
2190 % buildbot checkconfig master.cfg
2191 /usr/lib/python2.4/site-packages/buildbot/master.py:559: DeprecationWarning: c['sources'] is
2192 deprecated as of 0.7.6 and will be removed by 0.8.0 . Please use c['change_source'] instead.
2193 warnings.warn(m, DeprecationWarning)
2194 Config file is good!
2197 If the config file is simply broken, that will be caught too:
2200 % buildbot checkconfig master.cfg
2201 Traceback (most recent call last):
2202 File "/usr/lib/python2.4/site-packages/buildbot/scripts/runner.py", line 834, in doCheckConfig
2203 ConfigLoader(configFile)
2204 File "/usr/lib/python2.4/site-packages/buildbot/scripts/checkconfig.py", line 31, in __init__
2205 self.loadConfig(configFile)
2206 File "/usr/lib/python2.4/site-packages/buildbot/master.py", line 480, in loadConfig
2208 File "/home/warner/BuildBot/master/foolscap/master.cfg", line 90, in ?
2210 NameError: name 'bogus' is not defined
2214 @node Defining the Project, Change Sources and Schedulers, Testing the Config File, Configuration
2215 @section Defining the Project
2217 There are a couple of basic settings that you use to tell the buildbot
2218 what project it is working on. This information is used by status
2219 reporters to let users find out more about the codebase being
2220 exercised by this particular Buildbot installation.
2223 c['projectName'] = "Buildbot"
2224 c['projectURL'] = "http://buildbot.sourceforge.net/"
2225 c['buildbotURL'] = "http://localhost:8010/"
2228 @bcindex c['projectName']
2229 @code{projectName} is a short string will be used to describe the
2230 project that this buildbot is working on. For example, it is used as
2231 the title of the waterfall HTML page.
2233 @bcindex c['projectURL']
2234 @code{projectURL} is a string that gives a URL for the project as a
2235 whole. HTML status displays will show @code{projectName} as a link to
2236 @code{projectURL}, to provide a link from buildbot HTML pages to your
2237 project's home page.
2239 @bcindex c['buildbotURL']
2240 The @code{buildbotURL} string should point to the location where the
2241 buildbot's internal web server (usually the @code{html.Waterfall}
2242 page) is visible. This typically uses the port number set when you
2243 create the @code{Waterfall} object: the buildbot needs your help to
2244 figure out a suitable externally-visible host name.
2246 When status notices are sent to users (either by email or over IRC),
2247 @code{buildbotURL} will be used to create a URL to the specific build
2248 or problem that they are being notified about. It will also be made
2249 available to queriers (over IRC) who want to find out where to get
2250 more information about this buildbot.
2252 @bcindex c['logCompressionLimit']
2253 The @code{logCompressionLimit} enables bz2-compression of build logs on
2254 disk for logs that are bigger than the given size, or disables that
2255 completely if given @code{False}. The default value is 4k, which should
2256 be a reasonable default on most file systems. This setting has no impact
2257 on status plugins, and merely affects the required disk space on the
2258 master for build logs.
2261 @node Change Sources and Schedulers, Merging BuildRequests, Defining the Project, Configuration
2262 @section Change Sources and Schedulers
2264 @bcindex c['sources']
2265 @bcindex c['change_source']
2267 The @code{c['change_source']} key is the ChangeSource
2268 instance@footnote{To be precise, it is an object or a list of objects
2269 which all implement the @code{buildbot.interfaces.IChangeSource}
2270 Interface. It is unusual to have multiple ChangeSources, so this key
2271 accepts either a single ChangeSource or a sequence of them.} that
2272 defines how the buildmaster learns about source code changes. More
2273 information about what goes here is available in @xref{Getting Source
2277 from buildbot.changes.pb import PBChangeSource
2278 c['change_source'] = PBChangeSource()
2280 @bcindex c['schedulers']
2282 (note: in buildbot-0.7.5 and earlier, this key was named
2283 @code{c['sources']}, and required a list. @code{c['sources']} is
2284 deprecated as of buildbot-0.7.6 and is scheduled to be removed in a
2287 @code{c['schedulers']} is a list of Scheduler instances, each
2288 of which causes builds to be started on a particular set of
2289 Builders. The two basic Scheduler classes you are likely to start
2290 with are @code{Scheduler} and @code{Periodic}, but you can write a
2291 customized subclass to implement more complicated build scheduling.
2294 should always be specified by name (as keyword arguments), to allow
2295 for future expansion:
2298 sched = Scheduler(name="quick", builderNames=['lin', 'win'])
2301 All schedulers have several arguments in common:
2306 Each Scheduler must have a unique name. This is used in status
2307 displays, and is also available in the build property @code{scheduler}.
2311 This is the set of builders which this scheduler should trigger, specified
2312 as a list of names (strings).
2317 This is a dictionary specifying properties that will be transmitted
2318 to all builds started by this scheduler.
2322 Here is a brief catalog of the available Scheduler types. All these
2323 Schedulers are classes in @code{buildbot.scheduler}, and the
2324 docstrings there are the best source of documentation on the arguments
2328 * Scheduler Scheduler::
2329 * AnyBranchScheduler::
2330 * Dependent Scheduler::
2331 * Periodic Scheduler::
2332 * Nightly Scheduler::
2334 * Triggerable Scheduler::
2337 @node Scheduler Scheduler, AnyBranchScheduler, Change Sources and Schedulers, Change Sources and Schedulers
2338 @subsection Scheduler Scheduler
2339 @slindex buildbot.scheduler.Scheduler
2341 This is the original and still most popular Scheduler class. It follows
2342 exactly one branch, and starts a configurable tree-stable-timer after
2343 each change on that branch. When the timer expires, it starts a build
2344 on some set of Builders. The Scheduler accepts a @code{fileIsImportant}
2345 function which can be used to ignore some Changes if they do not
2346 affect any ``important'' files.
2348 The arguments to this scheduler are:
2358 This Scheduler will pay attention to a single branch, ignoring Changes
2359 that occur on other branches. Setting @code{branch} equal to the
2360 special value of @code{None} means it should only pay attention to
2361 the default branch. Note that @code{None} is a keyword, not a string,
2362 so you want to use @code{None} and not @code{"None"}.
2364 @item treeStableTimer
2365 The Scheduler will wait for this many seconds before starting the
2366 build. If new changes are made during this interval, the timer will be
2367 restarted, so really the build will be started after a change and then
2368 after this many seconds of inactivity.
2370 @item fileIsImportant
2371 A callable which takes one argument, a Change instance, and returns
2372 @code{True} if the change is worth building, and @code{False} if
2373 it is not. Unimportant Changes are accumulated until the build is
2374 triggered by an important change. The default value of None means
2375 that all Changes are important.
2378 A list of categories of changes that this scheduler will respond to. If this
2379 is specified, then any non-matching changes are ignored.
2386 from buildbot import scheduler
2387 quick = scheduler.Scheduler(name="quick",
2390 builderNames=["quick-linux", "quick-netbsd"])
2391 full = scheduler.Scheduler(name="full",
2393 treeStableTimer=5*60,
2394 builderNames=["full-linux", "full-netbsd", "full-OSX"])
2395 c['schedulers'] = [quick, full]
2398 In this example, the two ``quick'' builders are triggered 60 seconds
2399 after the tree has been changed. The ``full'' builds do not run quite
2400 so quickly (they wait 5 minutes), so hopefully if the quick builds
2401 fail due to a missing file or really simple typo, the developer can
2402 discover and fix the problem before the full builds are started. Both
2403 Schedulers only pay attention to the default branch: any changes
2404 on other branches are ignored by these Schedulers. Each Scheduler
2405 triggers a different set of Builders, referenced by name.
2407 @node AnyBranchScheduler, Dependent Scheduler, Scheduler Scheduler, Change Sources and Schedulers
2408 @subsection AnyBranchScheduler
2409 @slindex buildbot.scheduler.AnyBranchScheduler
2411 This scheduler uses a tree-stable-timer like the default one, but
2412 follows multiple branches at once. Each branch gets a separate timer.
2414 The arguments to this scheduler are:
2424 This Scheduler will pay attention to any number of branches, ignoring
2425 Changes that occur on other branches. Branches are specified just as
2426 for the @code{Scheduler} class.
2428 @item treeStableTimer
2429 The Scheduler will wait for this many seconds before starting the
2430 build. If new changes are made during this interval, the timer will be
2431 restarted, so really the build will be started after a change and then
2432 after this many seconds of inactivity.
2434 @item fileIsImportant
2435 A callable which takes one argument, a Change instance, and returns
2436 @code{True} if the change is worth building, and @code{False} if
2437 it is not. Unimportant Changes are accumulated until the build is
2438 triggered by an important change. The default value of None means
2439 that all Changes are important.
2442 @node Dependent Scheduler, Periodic Scheduler, AnyBranchScheduler, Change Sources and Schedulers
2443 @subsection Dependent Scheduler
2445 @cindex Dependencies
2446 @slindex buildbot.scheduler.Dependent
2448 It is common to wind up with one kind of build which should only be
2449 performed if the same source code was successfully handled by some
2450 other kind of build first. An example might be a packaging step: you
2451 might only want to produce .deb or RPM packages from a tree that was
2452 known to compile successfully and pass all unit tests. You could put
2453 the packaging step in the same Build as the compile and testing steps,
2454 but there might be other reasons to not do this (in particular you
2455 might have several Builders worth of compiles/tests, but only wish to
2456 do the packaging once). Another example is if you want to skip the
2457 ``full'' builds after a failing ``quick'' build of the same source
2458 code. Or, if one Build creates a product (like a compiled library)
2459 that is used by some other Builder, you'd want to make sure the
2460 consuming Build is run @emph{after} the producing one.
2462 You can use ``Dependencies'' to express this relationship
2463 to the Buildbot. There is a special kind of Scheduler named
2464 @code{scheduler.Dependent} that will watch an ``upstream'' Scheduler
2465 for builds to complete successfully (on all of its Builders). Each time
2466 that happens, the same source code (i.e. the same @code{SourceStamp})
2467 will be used to start a new set of builds, on a different set of
2468 Builders. This ``downstream'' scheduler doesn't pay attention to
2469 Changes at all. It only pays attention to the upstream scheduler.
2471 If the build fails on any of the Builders in the upstream set,
2472 the downstream builds will not fire. Note that, for SourceStamps
2473 generated by a ChangeSource, the @code{revision} is None, meaning HEAD.
2474 If any changes are committed between the time the upstream scheduler
2475 begins its build and the time the dependent scheduler begins its
2476 build, then those changes will be included in the downstream build.
2477 See the @pxref{Triggerable Scheduler} for a more flexible dependency
2478 mechanism that can avoid this problem.
2480 The arguments to this scheduler are:
2490 The upstream scheduler to watch. Note that this is an ``instance'',
2491 not the name of the scheduler.
2497 from buildbot import scheduler
2498 tests = scheduler.Scheduler("just-tests", None, 5*60,
2499 ["full-linux", "full-netbsd", "full-OSX"])
2500 package = scheduler.Dependent("build-package",
2501 tests, # upstream scheduler -- no quotes!
2502 ["make-tarball", "make-deb", "make-rpm"])
2503 c['schedulers'] = [tests, package]
2506 @node Periodic Scheduler, Nightly Scheduler, Dependent Scheduler, Change Sources and Schedulers
2507 @subsection Periodic Scheduler
2508 @slindex buildbot.scheduler.Periodic
2510 This simple scheduler just triggers a build every N seconds.
2512 The arguments to this scheduler are:
2521 @item periodicBuildTimer
2522 The time, in seconds, after which to start a build.
2528 from buildbot import scheduler
2529 nightly = scheduler.Periodic(name="nightly",
2530 builderNames=["full-solaris"],
2531 periodicBuildTimer=24*60*60)
2532 c['schedulers'] = [nightly]
2535 The Scheduler in this example just runs the full solaris build once
2536 per day. Note that this Scheduler only lets you control the time
2537 between builds, not the absolute time-of-day of each Build, so this
2538 could easily wind up a ``daily'' or ``every afternoon'' scheduler
2539 depending upon when it was first activated.
2541 @node Nightly Scheduler, Try Schedulers, Periodic Scheduler, Change Sources and Schedulers
2542 @subsection Nightly Scheduler
2543 @slindex buildbot.scheduler.Nightly
2545 This is highly configurable periodic build scheduler, which triggers
2546 a build at particular times of day, week, month, or year. The
2547 configuration syntax is very similar to the well-known @code{crontab}
2548 format, in which you provide values for minute, hour, day, and month
2549 (some of which can be wildcards), and a build is triggered whenever
2550 the current time matches the given constraints. This can run a build
2551 every night, every morning, every weekend, alternate Thursdays,
2552 on your boss's birthday, etc.
2554 Pass some subset of @code{minute}, @code{hour}, @code{dayOfMonth},
2555 @code{month}, and @code{dayOfWeek}; each may be a single number or
2556 a list of valid values. The builds will be triggered whenever the
2557 current time matches these values. Wildcards are represented by a
2558 '*' string. All fields default to a wildcard except 'minute', so
2559 with no fields this defaults to a build every hour, on the hour.
2560 The full list of parameters is:
2570 The branch to build, just as for @code{Scheduler}.
2573 The minute of the hour on which to start the build. This defaults
2574 to 0, meaning an hourly build.
2577 The hour of the day on which to start the build, in 24-hour notation.
2578 This defaults to *, meaning every hour.
2581 The month in which to start the build, with January = 1. This defaults
2582 to *, meaning every month.
2585 The day of the week to start a build, with Monday = 0. This defauls
2586 to *, meaning every day of the week.
2589 If this is true, then builds will not be scheduled at the designated time
2590 unless the source has changed since the previous build.
2593 For example, the following master.cfg clause will cause a build to be
2594 started every night at 3:00am:
2597 s = scheduler.Nightly(name='nightly',
2598 builderNames=['builder1', 'builder2'],
2603 This scheduler will perform a build each monday morning at 6:23am and
2604 again at 8:23am, but only if someone has committed code in the interim:
2607 s = scheduler.Nightly(name='BeforeWork',
2608 builderNames=['builder1'],
2615 The following runs a build every two hours, using Python's @code{range}
2619 s = Nightly(name='every2hours',
2620 builderNames=['builder1'],
2621 hour=range(0, 24, 2))
2624 Finally, this example will run only on December 24th:
2627 s = Nightly(name='SleighPreflightCheck',
2628 builderNames=['flying_circuits', 'radar'],
2635 @node Try Schedulers, Triggerable Scheduler, Nightly Scheduler, Change Sources and Schedulers
2636 @subsection Try Schedulers
2637 @slindex buildbot.scheduler.Try_Jobdir
2638 @slindex buildbot.scheduler.Try_Userpass
2640 This scheduler allows developers to use the @code{buildbot try}
2641 command to trigger builds of code they have not yet committed. See
2642 @ref{try} for complete details.
2644 Two implementations are available: @code{Try_Jobdir} and
2645 @code{Try_Userpass}. The former monitors a job directory, specified
2646 by the @code{jobdir} parameter, while the latter listens for PB
2647 connections on a specific @code{port}, and authenticates against
2650 @node Triggerable Scheduler, , Try Schedulers, Change Sources and Schedulers
2651 @subsection Triggerable Scheduler
2653 @slindex buildbot.scheduler.Triggerable
2655 The @code{Triggerable} scheduler waits to be triggered by a Trigger
2656 step (see @ref{Triggering Schedulers}) in another build. That step
2657 can optionally wait for the scheduler's builds to complete. This
2658 provides two advantages over Dependent schedulers. First, the same
2659 scheduler can be triggered from multiple builds. Second, the ability
2660 to wait for a Triggerable's builds to complete provides a form of
2661 "subroutine call", where one or more builds can "call" a scheduler
2662 to perform some work for them, perhaps on other buildslaves.
2664 The parameters are just the basics:
2672 This class is only useful in conjunction with the @code{Trigger} step.
2673 Here is a fully-worked example:
2676 from buildbot import scheduler
2677 from buildbot.process import factory
2678 from buildbot.steps import trigger
2680 checkin = scheduler.Scheduler(name="checkin",
2682 treeStableTimer=5*60,
2683 builderNames=["checkin"])
2684 nightly = scheduler.Nightly(name='nightly',
2685 builderNames=['nightly'],
2689 mktarball = scheduler.Triggerable(name="mktarball",
2690 builderNames=["mktarball"])
2691 build = scheduler.Triggerable(name="build-all-platforms",
2692 builderNames=["build-all-platforms"])
2693 test = scheduler.Triggerable(name="distributed-test",
2694 builderNames=["distributed-test"])
2695 package = scheduler.Triggerable(name="package-all-platforms",
2696 builderNames=["package-all-platforms"])
2698 c['schedulers'] = [checkin, nightly, build, test, package]
2700 # on checkin, make a tarball, build it, and test it
2701 checkin_factory = factory.BuildFactory()
2702 checkin_factory.addStep(trigger.Trigger(schedulerNames=['mktarball'],
2703 waitForFinish=True))
2704 checkin_factory.addStep(trigger.Trigger(schedulerNames=['build-all-platforms'],
2705 waitForFinish=True))
2706 checkin_factory.addStep(trigger.Trigger(schedulerNames=['distributed-test'],
2707 waitForFinish=True))
2709 # and every night, make a tarball, build it, and package it
2710 nightly_factory = factory.BuildFactory()
2711 nightly_factory.addStep(trigger.Trigger(schedulerNames=['mktarball'],
2712 waitForFinish=True))
2713 nightly_factory.addStep(trigger.Trigger(schedulerNames=['build-all-platforms'],
2714 waitForFinish=True))
2715 nightly_factory.addStep(trigger.Trigger(schedulerNames=['package-all-platforms'],
2716 waitForFinish=True))
2719 @node Merging BuildRequests, Setting the slaveport, Change Sources and Schedulers, Configuration
2720 @section Merging BuildRequests
2722 @bcindex c['mergeRequests']
2724 By default, buildbot merges BuildRequests that have the compatible
2725 SourceStamps. This behaviour can be customized with the
2726 @code{c['mergeRequests']} configuration key. This key specifies a function
2727 which is caleld with three arguments: a @code{Builder} and two
2728 @code{BuildRequest} objects. It should return true if the requests can be
2729 merged. For example:
2732 def mergeRequests(builder, req1, req2):
2733 """Don't merge buildrequest at all"""
2735 c['mergeRequests'] = mergeRequests
2738 In many cases, the details of the SourceStamps and BuildRequests are important.
2739 In this example, only BuildRequests with the same "reason" are merged; thus
2740 developers forcing builds for different reasons will see distinct builds.
2743 def mergeRequests(builder, req1, req2):
2744 if req1.source.canBeMergedWith(req2.source) and req1.reason == req2.reason:
2747 c['mergeRequests'] = mergeRequests
2750 @node Setting the slaveport, Buildslave Specifiers, Merging BuildRequests, Configuration
2751 @section Setting the slaveport
2753 @bcindex c['slavePortnum']
2755 The buildmaster will listen on a TCP port of your choosing for
2756 connections from buildslaves. It can also use this port for
2757 connections from remote Change Sources, status clients, and debug
2758 tools. This port should be visible to the outside world, and you'll
2759 need to tell your buildslave admins about your choice.
2761 It does not matter which port you pick, as long it is externally
2762 visible, however you should probably use something larger than 1024,
2763 since most operating systems don't allow non-root processes to bind to
2764 low-numbered ports. If your buildmaster is behind a firewall or a NAT
2765 box of some sort, you may have to configure your firewall to permit
2766 inbound connections to this port.
2769 c['slavePortnum'] = 10000
2772 @code{c['slavePortnum']} is a @emph{strports} specification string,
2773 defined in the @code{twisted.application.strports} module (try
2774 @command{pydoc twisted.application.strports} to get documentation on
2775 the format). This means that you can have the buildmaster listen on a
2776 localhost-only port by doing:
2779 c['slavePortnum'] = "tcp:10000:interface=127.0.0.1"
2782 This might be useful if you only run buildslaves on the same machine,
2783 and they are all configured to contact the buildmaster at
2784 @code{localhost:10000}.
2787 @node Buildslave Specifiers, On-Demand ("Latent") Buildslaves, Setting the slaveport, Configuration
2788 @section Buildslave Specifiers
2789 @bcindex c['slaves']
2791 The @code{c['slaves']} key is a list of known buildslaves. In the common case,
2792 each buildslave is defined by an instance of the BuildSlave class. It
2793 represents a standard, manually started machine that will try to connect to
2794 the buildbot master as a slave. Contrast these with the "on-demand" latent
2795 buildslaves, such as the Amazon Web Service Elastic Compute Cloud latent
2796 buildslave discussed below.
2798 The BuildSlave class is instantiated with two values: (slavename,
2799 slavepassword). These are the same two values that need to be provided to the
2800 buildslave administrator when they create the buildslave.
2802 The slavenames must be unique, of course. The password exists to
2803 prevent evildoers from interfering with the buildbot by inserting
2804 their own (broken) buildslaves into the system and thus displacing the
2807 Buildslaves with an unrecognized slavename or a non-matching password
2808 will be rejected when they attempt to connect, and a message
2809 describing the problem will be put in the log file (see @ref{Logfiles}).
2812 from buildbot.buildslave import BuildSlave
2813 c['slaves'] = [BuildSlave('bot-solaris', 'solarispasswd')
2814 BuildSlave('bot-bsd', 'bsdpasswd')
2819 @code{BuildSlave} objects can also be created with an optional
2820 @code{properties} argument, a dictionary specifying properties that
2821 will be available to any builds performed on this slave. For example:
2824 from buildbot.buildslave import BuildSlave
2825 c['slaves'] = [BuildSlave('bot-solaris', 'solarispasswd',
2826 properties=@{'os':'solaris'@}),
2830 The @code{BuildSlave} constructor can also take an optional
2831 @code{max_builds} parameter to limit the number of builds that it
2832 will execute simultaneously:
2835 from buildbot.buildslave import BuildSlave
2836 c['slaves'] = [BuildSlave("bot-linux", "linuxpassword", max_builds=2)]
2839 Historical note: in buildbot-0.7.5 and earlier, the @code{c['bots']}
2840 key was used instead, and it took a list of (name, password) tuples.
2841 This key is accepted for backwards compatibility, but is deprecated as
2842 of 0.7.6 and will go away in some future release.
2845 * When Buildslaves Go Missing::
2848 @node When Buildslaves Go Missing, , , Buildslave Specifiers
2849 @subsection When Buildslaves Go Missing
2851 Sometimes, the buildslaves go away. One very common reason for this is
2852 when the buildslave process is started once (manually) and left
2853 running, but then later the machine reboots and the process is not
2854 automatically restarted.
2856 If you'd like to have the administrator of the buildslave (or other
2857 people) be notified by email when the buildslave has been missing for
2858 too long, just add the @code{notify_on_missing=} argument to the
2859 @code{BuildSlave} definition:
2862 c['slaves'] = [BuildSlave('bot-solaris', 'solarispasswd',
2863 notify_on_missing="bob@@example.com"),
2867 By default, this will send email when the buildslave has been
2868 disconnected for more than one hour. Only one email per
2869 connection-loss event will be sent. To change the timeout, use
2870 @code{missing_timeout=} and give it a number of seconds (the default
2873 You can have the buildmaster send email to multiple recipients: just
2874 provide a list of addresses instead of a single one:
2877 c['slaves'] = [BuildSlave('bot-solaris', 'solarispasswd',
2878 notify_on_missing=["bob@@example.com",
2879 "alice@@example.org"],
2880 missing_timeout=300, # notify after 5 minutes
2885 The email sent this way will use a MailNotifier (@pxref{MailNotifier})
2886 status target, if one is configured. This provides a way for you to
2887 control the ``from'' address of the email, as well as the relayhost
2888 (aka ``smarthost'') to use as an SMTP server. If no MailNotifier is
2889 configured on this buildmaster, the buildslave-missing emails will be
2890 sent using a default configuration.
2892 Note that if you want to have a MailNotifier for buildslave-missing
2893 emails but not for regular build emails, just create one with
2894 builders=[], as follows:
2897 from buildbot.status import mail
2898 m = mail.MailNotifier(fromaddr="buildbot@@localhost", builders=[],
2899 relayhost="smtp.example.org")
2900 c['status'].append(m)
2901 c['slaves'] = [BuildSlave('bot-solaris', 'solarispasswd',
2902 notify_on_missing="bob@@example.com"),
2906 @node On-Demand ("Latent") Buildslaves, Defining Global Properties, Buildslave Specifiers, Configuration
2907 @section On-Demand ("Latent") Buildslaves
2909 The standard buildbot model has slaves started manually. The previous section
2910 described how to configure the master for this approach.
2912 Another approach is to let the buildbot master start slaves when builds are
2913 ready, on-demand. Thanks to services such as Amazon Web Services' Elastic
2914 Compute Cloud ("AWS EC2"), this is relatively easy to set up, and can be
2915 very useful for some situations.
2917 The buildslaves that are started on-demand are called "latent" buildslaves.
2918 As of this writing, buildbot ships with an abstract base class for building
2919 latent buildslaves, and a concrete implementation for AWS EC2.
2922 * Amazon Web Services Elastic Compute Cloud ("AWS EC2")::
2923 * Dangers with Latent Buildslaves::
2924 * Writing New Latent Buildslaves::
2927 @node Amazon Web Services Elastic Compute Cloud ("AWS EC2"), Dangers with Latent Buildslaves, , On-Demand ("Latent") Buildslaves
2928 @subsection Amazon Web Services Elastic Compute Cloud ("AWS EC2")
2930 @url{http://aws.amazon.com/ec2/,,AWS EC2} is a web service that allows you to
2931 start virtual machines in an Amazon data center. Please see their website for
2932 details, incuding costs. Using the AWS EC2 latent buildslaves involves getting
2933 an EC2 account with AWS and setting up payment; customizing one or more EC2
2934 machine images ("AMIs") on your desired operating system(s) and publishing
2935 them (privately if needed); and configuring the buildbot master to know how to
2936 start your customized images for "substantiating" your latent slaves.
2939 * Get an AWS EC2 Account::
2941 * Configure the Master with an EC2LatentBuildSlave::
2944 @node Get an AWS EC2 Account, Create an AMI, , Amazon Web Services Elastic Compute Cloud ("AWS EC2")
2945 @subsubsection Get an AWS EC2 Account
2947 To start off, to use the AWS EC2 latent buildslave, you need to get an AWS
2948 developer account and sign up for EC2. These instructions may help you get
2953 Go to http://aws.amazon.com/ and click to "Sign Up Now" for an AWS account.
2956 Once you are logged into your account, you need to sign up for EC2.
2957 Instructions for how to do this have changed over time because Amazon changes
2958 their website, so the best advice is to hunt for it. After signing up for EC2,
2959 it may say it wants you to upload an x.509 cert. You will need this to create
2960 images (see below) but it is not technically necessary for the buildbot master
2964 You must enter a valid credit card before you will be able to use EC2. Do that
2965 under 'Payment Method'.
2968 Make sure you're signed up for EC2 by going to 'Your Account'->'Account
2969 Activity' and verifying EC2 is listed.
2972 @node Create an AMI, Configure the Master with an EC2LatentBuildSlave, Get an AWS EC2 Account, Amazon Web Services Elastic Compute Cloud ("AWS EC2")
2973 @subsubsection Create an AMI
2975 Now you need to create an AMI and configure the master. You may need to
2976 run through this cycle a few times to get it working, but these instructions
2977 should get you started.
2979 Creating an AMI is out of the scope of this document. The
2980 @url{http://docs.amazonwebservices.com/AWSEC2/latest/GettingStartedGuide/,,EC2 Getting Started Guide}
2981 is a good resource for this task. Here are a few additional hints.
2985 When an instance of the image starts, it needs to automatically start a
2986 buildbot slave that connects to your master (to create a buildbot slave,
2987 @pxref{Creating a buildslave}; to make a daemon,
2988 @pxref{Launching the daemons}).
2991 You may want to make an instance of the buildbot slave, configure it as a
2992 standard buildslave in the master (i.e., not as a latent slave), and test and
2993 debug it that way before you turn it into an AMI and convert to a latent
2994 slave in the master.
2997 @node Configure the Master with an EC2LatentBuildSlave, , Create an AMI, Amazon Web Services Elastic Compute Cloud ("AWS EC2")
2998 @subsubsection Configure the Master with an EC2LatentBuildSlave
3000 Now let's assume you have an AMI that should work with the
3001 EC2LatentBuildSlave. It's now time to set up your buildbot master
3004 You will need some information from your AWS account: the "Access Key Id" and
3005 the "Secret Access Key". If you've built the AMI yourself, you probably
3006 already are familiar with these values. If you have not, and someone has
3007 given you access to an AMI, these hints may help you find the necessary
3012 While logged into your AWS account, find the "Access Identifiers" link (either
3013 on the left, or via "Your Account" -> "Access Identifiers".
3016 On the page, you'll see alphanumeric values for "Your Access Key Id:" and
3017 "Your Secret Access Key:". Make a note of these. Later on, we'll call the
3018 first one your "identifier" and the second one your "secret_identifier."
3021 When creating an EC2LatentBuildSlave in the buildbot master configuration,
3022 the first three arguments are required. The name and password are the first
3023 two arguments, and work the same as with normal buildslaves. The next
3024 argument specifies the type of the EC2 virtual machine (available options as
3025 of this writing include "m1.small", "m1.large", 'm1.xlarge", "c1.medium",
3026 and "c1.xlarge"; see the EC2 documentation for descriptions of these
3029 Here is the simplest example of configuring an EC2 latent buildslave. It
3030 specifies all necessary remaining values explicitly in the instantiation.
3033 from buildbot.ec2buildslave import EC2LatentBuildSlave
3034 c['slaves'] = [EC2LatentBuildSlave('bot1', 'sekrit', 'm1.large',
3036 identifier='publickey',
3037 secret_identifier='privatekey'
3041 The "ami" argument specifies the AMI that the master should start. The
3042 "identifier" argument specifies the AWS "Access Key Id," and the
3043 "secret_identifier" specifies the AWS "Secret Access Key." Both the AMI and
3044 the account information can be specified in alternate ways.
3046 Note that whoever has your identifier and secret_identifier values can request
3047 AWS work charged to your account, so these values need to be carefully
3048 protected. Another way to specify these access keys is to put them in a
3049 separate file. You can then make the access privileges stricter for this
3050 separate file, and potentially let more people read your main configuration
3053 By default, you can make an .ec2 directory in the home folder of the user
3054 running the buildbot master. In that directory, create a file called aws_id.
3055 The first line of that file should be your access key id; the second line
3056 should be your secret access key id. Then you can instantiate the build slave
3060 from buildbot.ec2buildslave import EC2LatentBuildSlave
3061 c['slaves'] = [EC2LatentBuildSlave('bot1', 'sekrit', 'm1.large',
3065 If you want to put the key information in another file, use the
3066 "aws_id_file_path" initialization argument.
3068 Previous examples used a particular AMI. If the Buildbot master will be
3069 deployed in a process-controlled environment, it may be convenient to
3070 specify the AMI more flexibly. Rather than specifying an individual AMI,
3071 specify one or two AMI filters.
3073 In all cases, the AMI that sorts last by its location (the S3 bucket and
3074 manifest name) will be preferred.
3076 One available filter is to specify the acceptable AMI owners, by AWS account
3077 number (the 12 digit number, usually rendered in AWS with hyphens like
3078 "1234-5678-9012", should be entered as in integer).
3081 from buildbot.ec2buildslave import EC2LatentBuildSlave
3082 bot1 = EC2LatentBuildSlave('bot1', 'sekrit', 'm1.large',
3083 valid_ami_owners=[11111111111,
3085 identifier='publickey',
3086 secret_identifier='privatekey'
3090 The other available filter is to provide a regular expression string that
3091 will be matched against each AMI's location (the S3 bucket and manifest name).
3094 from buildbot.ec2buildslave import EC2LatentBuildSlave
3095 bot1 = EC2LatentBuildSlave(
3096 'bot1', 'sekrit', 'm1.large',
3097 valid_ami_location_regex=r'buildbot\-.*/image.manifest.xml',
3098 identifier='publickey', secret_identifier='privatekey')
3101 The regular expression can specify a group, which will be preferred for the
3102 sorting. Only the first group is used; subsequent groups are ignored.
3105 from buildbot.ec2buildslave import EC2LatentBuildSlave
3106 bot1 = EC2LatentBuildSlave(
3107 'bot1', 'sekrit', 'm1.large',
3108 valid_ami_location_regex=r'buildbot\-.*\-(.*)/image.manifest.xml',
3109 identifier='publickey', secret_identifier='privatekey')
3112 If the group can be cast to an integer, it will be. This allows 10 to sort
3113 after 1, for instance.
3116 from buildbot.ec2buildslave import EC2LatentBuildSlave
3117 bot1 = EC2LatentBuildSlave(
3118 'bot1', 'sekrit', 'm1.large',
3119 valid_ami_location_regex=r'buildbot\-.*\-(\d+)/image.manifest.xml',
3120 identifier='publickey', secret_identifier='privatekey')
3123 In addition to using the password as a handshake between the master and the
3124 slave, you may want to use a firewall to assert that only machines from a
3125 specific IP can connect as slaves. This is possible with AWS EC2 by using
3126 the Elastic IP feature. To configure, generate a Elastic IP in AWS, and then
3127 specify it in your configuration using the "elastic_ip" argument.
3130 from buildbot.ec2buildslave import EC2LatentBuildSlave
3131 c['slaves'] = [EC2LatentBuildSlave('bot1', 'sekrit', 'm1.large',
3133 identifier='publickey',
3134 secret_identifier='privatekey',
3135 elastic_ip='208.77.188.166'
3139 The EC2LatentBuildSlave supports all other configuration from the standard
3140 BuildSlave. The "missing_timeout" and "notify_on_missing" specify how long
3141 to wait for an EC2 instance to attach before considering the attempt to have
3142 failed, and email addresses to alert, respectively. "missing_timeout"
3143 defaults to 20 minutes.
3145 The "build_wait_timeout" allows you to specify how long an EC2LatentBuildSlave
3146 should wait after a build for another build before it shuts down the EC2
3147 instance. It defaults to 10 minutes.
3149 "keypair_name" and "security_name" allow you to specify different names for
3150 these AWS EC2 values. They both default to "latent_buildbot_slave".
3152 @node Dangers with Latent Buildslaves, Writing New Latent Buildslaves, Amazon Web Services Elastic Compute Cloud ("AWS EC2"), On-Demand ("Latent") Buildslaves
3153 @subsection Dangers with Latent Buildslaves
3155 Any latent build slave that interacts with a for-fee service, such as the
3156 EC2LatentBuildSlave, brings significant risks. As already identified, the
3157 configuraton will need access to account information that, if obtained by a
3158 criminal, can be used to charge services to your account. Also, bugs in the
3159 buildbot software may lead to unnecessary charges. In particular, if the
3160 master neglects to shut down an instance for some reason, a virtual machine
3161 may be running unnecessarily, charging against your account. Manual and/or
3162 automatic (e.g. nagios with a plugin using a library like boto)
3163 double-checking may be appropriate.
3165 A comparitively trivial note is that currently if two instances try to attach
3166 to the same latent buildslave, it is likely that the system will become
3167 confused. This should not occur, unless, for instance, you configure a normal
3168 build slave to connect with the authentication of a latent buildbot. If the
3169 situation occurs, stop all attached instances and restart the master.
3171 @node Writing New Latent Buildslaves, , Dangers with Latent Buildslaves, On-Demand ("Latent") Buildslaves
3172 @subsection Writing New Latent Buildslaves
3174 Writing a new latent buildslave should only require subclassing
3175 @code{buildbot.buildslave.AbstractLatentBuildSlave} and implementing
3176 start_instance and stop_instance.
3179 def start_instance(self):
3180 # responsible for starting instance that will try to connect with this
3181 # master. Should return deferred. Problems should use an errback. The
3182 # callback value can be None, or can be an iterable of short strings to
3183 # include in the "substantiate success" status message, such as
3184 # identifying the instance that started.
3185 raise NotImplementedError
3187 def stop_instance(self, fast=False):
3188 # responsible for shutting down instance. Return a deferred. If `fast`,
3189 # we're trying to shut the master down, so callback as soon as is safe.
3190 # Callback value is ignored.
3191 raise NotImplementedError
3194 See @code{buildbot.ec2buildslave.EC2LatentBuildSlave} for an example, or see the
3195 test example @code{buildbot.test_slaves.FakeLatentBuildSlave}.
3197 @node Defining Global Properties, Defining Builders, On-Demand ("Latent") Buildslaves, Configuration
3198 @section Defining Global Properties
3199 @bcindex c['properties']
3202 The @code{'properties'} configuration key defines a dictionary
3203 of properties that will be available to all builds started by the
3207 c['properties'] = @{
3208 'Widget-version' : '1.2',
3209 'release-stage' : 'alpha'
3213 @node Defining Builders, Defining Status Targets, Defining Global Properties, Configuration
3214 @section Defining Builders
3216 @bcindex c['builders']
3218 The @code{c['builders']} key is a list of dictionaries which specify
3219 the Builders. The Buildmaster runs a collection of Builders, each of
3220 which handles a single type of build (e.g. full versus quick), on a
3221 single build slave. A Buildbot which makes sure that the latest code
3222 (``HEAD'') compiles correctly across four separate architecture will
3223 have four Builders, each performing the same build but on different
3224 slaves (one per platform).
3226 Each Builder gets a separate column in the waterfall display. In
3227 general, each Builder runs independently (although various kinds of
3228 interlocks can cause one Builder to have an effect on another).
3230 Each Builder specification dictionary has several required keys:
3234 This specifies the Builder's name, which is used in status
3238 This specifies which buildslave will be used by this Builder.
3239 @code{slavename} must appear in the @code{c['slaves']} list. Each
3240 buildslave can accomodate multiple Builders.
3243 If you provide @code{slavenames} instead of @code{slavename}, you can
3244 give a list of buildslaves which are capable of running this Builder.
3245 If multiple buildslaves are available for any given Builder, you will
3246 have some measure of redundancy: in case one slave goes offline, the
3247 others can still keep the Builder working. In addition, multiple
3248 buildslaves will allow multiple simultaneous builds for the same
3249 Builder, which might be useful if you have a lot of forced or ``try''
3250 builds taking place.
3252 If you use this feature, it is important to make sure that the
3253 buildslaves are all, in fact, capable of running the given build. The
3254 slave hosts should be configured similarly, otherwise you will spend a
3255 lot of time trying (unsuccessfully) to reproduce a failure that only
3256 occurs on some of the buildslaves and not the others. Different
3257 platforms, operating systems, versions of major programs or libraries,
3258 all these things mean you should use separate Builders.
3261 This specifies the name of a subdirectory (under the base directory)
3262 in which everything related to this builder will be placed. On the
3263 buildmaster, this holds build status information. On the buildslave,
3264 this is where checkouts, compiles, and tests are run.
3267 This is a @code{buildbot.process.factory.BuildFactory} instance which
3268 controls how the build is performed. Full details appear in their own
3269 chapter, @xref{Build Process}. Parameters like the location of the CVS
3270 repository and the compile-time options used for the build are
3271 generally provided as arguments to the factory's constructor.
3275 Other optional keys may be set on each Builder:
3280 If provided, this is a string that identifies a category for the
3281 builder to be a part of. Status clients can limit themselves to a
3282 subset of the available categories. A common use for this is to add
3283 new builders to your setup (for a new module, or for a new buildslave)
3284 that do not work correctly yet and allow you to integrate them with
3285 the active builders. You can put these new builders in a test
3286 category, make your main status clients ignore them, and have only
3287 private status clients pick them up. As soon as they work, you can
3288 move them over to the active category.
3293 @node Defining Status Targets, Debug options, Defining Builders, Configuration
3294 @section Defining Status Targets
3296 The Buildmaster has a variety of ways to present build status to
3297 various users. Each such delivery method is a ``Status Target'' object
3298 in the configuration's @code{status} list. To add status targets, you
3299 just append more objects to this list:
3301 @bcindex c['status']
3306 from buildbot.status import html
3307 c['status'].append(html.Waterfall(http_port=8010))
3309 from buildbot.status import mail
3310 m = mail.MailNotifier(fromaddr="buildbot@@localhost",
3311 extraRecipients=["builds@@lists.example.com"],
3312 sendToInterestedUsers=False)
3313 c['status'].append(m)
3315 from buildbot.status import words
3316 c['status'].append(words.IRC(host="irc.example.com", nick="bb",
3317 channels=["#example"]))
3320 Status delivery has its own chapter, @xref{Status Delivery}, in which
3321 all the built-in status targets are documented.
3324 @node Debug options, , Defining Status Targets, Configuration
3325 @section Debug options
3328 @bcindex c['debugPassword']
3329 If you set @code{c['debugPassword']}, then you can connect to the
3330 buildmaster with the diagnostic tool launched by @code{buildbot
3331 debugclient MASTER:PORT}. From this tool, you can reload the config
3332 file, manually force builds, and inject changes, which may be useful
3333 for testing your buildmaster without actually commiting changes to
3334 your repository (or before you have the Change Sources set up). The
3335 debug tool uses the same port number as the slaves do:
3336 @code{c['slavePortnum']}, and is authenticated with this password.
3339 c['debugPassword'] = "debugpassword"
3342 @bcindex c['manhole']
3343 If you set @code{c['manhole']} to an instance of one of the classes in
3344 @code{buildbot.manhole}, you can telnet or ssh into the buildmaster
3345 and get an interactive Python shell, which may be useful for debugging
3346 buildbot internals. It is probably only useful for buildbot
3347 developers. It exposes full access to the buildmaster's account
3348 (including the ability to modify and delete files), so it should not
3349 be enabled with a weak or easily guessable password.
3351 There are three separate @code{Manhole} classes. Two of them use SSH,
3352 one uses unencrypted telnet. Two of them use a username+password
3353 combination to grant access, one of them uses an SSH-style
3354 @file{authorized_keys} file which contains a list of ssh public keys.
3357 @item manhole.AuthorizedKeysManhole
3358 You construct this with the name of a file that contains one SSH
3359 public key per line, just like @file{~/.ssh/authorized_keys}. If you
3360 provide a non-absolute filename, it will be interpreted relative to
3361 the buildmaster's base directory.
3363 @item manhole.PasswordManhole
3364 This one accepts SSH connections but asks for a username and password
3365 when authenticating. It accepts only one such pair.
3368 @item manhole.TelnetManhole
3369 This accepts regular unencrypted telnet connections, and asks for a
3370 username/password pair before providing access. Because this
3371 username/password is transmitted in the clear, and because Manhole
3372 access to the buildmaster is equivalent to granting full shell
3373 privileges to both the buildmaster and all the buildslaves (and to all
3374 accounts which then run code produced by the buildslaves), it is
3375 highly recommended that you use one of the SSH manholes instead.
3381 from buildbot import manhole
3382 c['manhole'] = manhole.AuthorizedKeysManhole(1234, "authorized_keys")
3383 c['manhole'] = manhole.PasswordManhole(1234, "alice", "mysecretpassword")
3384 c['manhole'] = manhole.TelnetManhole(1234, "bob", "snoop_my_password_please")
3387 The @code{Manhole} instance can be configured to listen on a specific
3388 port. You may wish to have this listening port bind to the loopback
3389 interface (sometimes known as ``lo0'', ``localhost'', or 127.0.0.1) to
3390 restrict access to clients which are running on the same host.
3393 from buildbot.manhole import PasswordManhole
3394 c['manhole'] = PasswordManhole("tcp:9999:interface=127.0.0.1","admin","passwd")
3397 To have the @code{Manhole} listen on all interfaces, use
3398 @code{"tcp:9999"} or simply 9999. This port specification uses
3399 @code{twisted.application.strports}, so you can make it listen on SSL
3400 or even UNIX-domain sockets if you want.
3402 Note that using any Manhole requires that the TwistedConch package be
3403 installed, and that you be using Twisted version 2.0 or later.
3405 The buildmaster's SSH server will use a different host key than the
3406 normal sshd running on a typical unix host. This will cause the ssh
3407 client to complain about a ``host key mismatch'', because it does not
3408 realize there are two separate servers running on the same host. To
3409 avoid this, use a clause like the following in your @file{.ssh/config}
3413 Host remotehost-buildbot
3415 HostKeyAlias remotehost-buildbot
3417 # use 'user' if you use PasswordManhole and your name is not 'admin'.
3418 # if you use AuthorizedKeysManhole, this probably doesn't matter.
3423 @node Getting Source Code Changes, Build Process, Configuration, Top
3424 @chapter Getting Source Code Changes
3426 The most common way to use the Buildbot is centered around the idea of
3427 @code{Source Trees}: a directory tree filled with source code of some form
3428 which can be compiled and/or tested. Some projects use languages that don't
3429 involve any compilation step: nevertheless there may be a @code{build} phase
3430 where files are copied or rearranged into a form that is suitable for
3431 installation. Some projects do not have unit tests, and the Buildbot is
3432 merely helping to make sure that the sources can compile correctly. But in
3433 all of these cases, the thing-being-tested is a single source tree.
3435 A Version Control System mantains a source tree, and tells the
3436 buildmaster when it changes. The first step of each Build is typically
3437 to acquire a copy of some version of this tree.
3439 This chapter describes how the Buildbot learns about what Changes have
3440 occurred. For more information on VC systems and Changes, see
3441 @ref{Version Control Systems}.
3446 * Choosing ChangeSources::
3447 * CVSToys - PBService::
3448 * Mail-parsing ChangeSources::
3460 @node Change Sources, Choosing ChangeSources, Getting Source Code Changes, Getting Source Code Changes
3461 @section Change Sources
3463 @c TODO: rework this, the one-buildmaster-one-tree thing isn't quite
3464 @c so narrow-minded anymore
3466 Each Buildmaster watches a single source tree. Changes can be provided
3467 by a variety of ChangeSource types, however any given project will
3468 typically have only a single ChangeSource active. This section
3469 provides a description of all available ChangeSource types and
3470 explains how to set up each of them.
3472 There are a variety of ChangeSources available, some of which are
3473 meant to be used in conjunction with other tools to deliver Change
3474 events from the VC repository to the buildmaster.
3479 This ChangeSource opens a TCP connection from the buildmaster to a
3480 waiting FreshCVS daemon that lives on the repository machine, and
3481 subscribes to hear about Changes.
3484 This one watches a local maildir-format inbox for email sent out by
3485 the repository when a change is made. When a message arrives, it is
3486 parsed to create the Change object. A variety of parsing functions are
3487 available to accomodate different email-sending tools.
3489 @item PBChangeSource
3490 This ChangeSource listens on a local TCP socket for inbound
3491 connections from a separate tool. Usually, this tool would be run on
3492 the VC repository machine in a commit hook. It is expected to connect
3493 to the TCP socket and send a Change message over the network
3494 connection. The @command{buildbot sendchange} command is one example
3495 of a tool that knows how to send these messages, so you can write a
3496 commit script for your VC system that calls it to deliver the Change.
3497 There are other tools in the contrib/ directory that use the same
3502 As a quick guide, here is a list of VC systems and the ChangeSources
3503 that might be useful with them. All of these ChangeSources are in the
3504 @code{buildbot.changes} module.
3510 @item freshcvs.FreshCVSSource (connected via TCP to the freshcvs daemon)
3511 @item mail.FCMaildirSource (watching for email sent by a freshcvs daemon)
3512 @item mail.BonsaiMaildirSource (watching for email sent by Bonsai)
3513 @item mail.SyncmailMaildirSource (watching for email sent by syncmail)
3514 @item pb.PBChangeSource (listening for connections from @code{buildbot
3515 sendchange} run in a loginfo script)
3516 @item pb.PBChangeSource (listening for connections from a long-running
3517 @code{contrib/viewcvspoll.py} polling process which examines the ViewCVS
3523 @item pb.PBChangeSource (listening for connections from
3524 @code{contrib/svn_buildbot.py} run in a postcommit script)
3525 @item pb.PBChangeSource (listening for connections from a long-running
3526 @code{contrib/svn_watcher.py} or @code{contrib/svnpoller.py} polling
3528 @item mail.SVNCommitEmailMaildirSource (watching for email sent by commit-email.pl)
3529 @item svnpoller.SVNPoller (polling the SVN repository)
3534 @item pb.PBChangeSource (listening for connections from
3535 @code{contrib/darcs_buildbot.py} in a commit script
3540 @item pb.PBChangeSource (listening for connections from
3541 @code{contrib/hg_buildbot.py} run in an 'incoming' hook)
3542 @item pb.PBChangeSource (listening for connections from
3543 @code{buildbot/changes/hgbuildbot.py} run as an in-process 'changegroup'
3549 @item pb.PBChangeSource (listening for connections from
3550 @code{contrib/arch_buildbot.py} run in a commit hook)
3553 @item Bzr (the newer Bazaar)
3555 @item pb.PBChangeSource (listening for connections from
3556 @code{contrib/bzr_buildbot.py} run in a post-change-branch-tip or commit hook)
3557 @item @code{contrib/bzr_buildbot.py}'s BzrPoller (polling the Bzr repository)
3562 @item pb.PBChangeSource (listening for connections from
3563 @code{contrib/git_buildbot.py} run in the post-receive hook)
3568 All VC systems can be driven by a PBChangeSource and the
3569 @code{buildbot sendchange} tool run from some form of commit script.
3570 If you write an email parsing function, they can also all be driven by
3571 a suitable @code{MaildirSource}.
3574 @node Choosing ChangeSources, CVSToys - PBService, Change Sources, Getting Source Code Changes
3575 @section Choosing ChangeSources
3577 The @code{master.cfg} configuration file has a dictionary key named
3578 @code{BuildmasterConfig['change_source']}, which holds the active
3579 @code{IChangeSource} object. The config file will typically create an
3580 object from one of the classes described below and stuff it into this
3583 Each buildmaster typically has just a single ChangeSource, since it is
3584 only watching a single source tree. But if, for some reason, you need
3585 multiple sources, just set @code{c['change_source']} to a list of
3586 ChangeSources.. it will accept that too.
3589 s = FreshCVSSourceNewcred(host="host", port=4519,
3590 user="alice", passwd="secret",
3592 BuildmasterConfig['change_source'] = [s]
3595 Each source tree has a nominal @code{top}. Each Change has a list of
3596 filenames, which are all relative to this top location. The
3597 ChangeSource is responsible for doing whatever is necessary to
3598 accomplish this. Most sources have a @code{prefix} argument: a partial
3599 pathname which is stripped from the front of all filenames provided to
3600 that @code{ChangeSource}. Files which are outside this sub-tree are
3601 ignored by the changesource: it does not generate Changes for those
3605 @node CVSToys - PBService, Mail-parsing ChangeSources, Choosing ChangeSources, Getting Source Code Changes
3606 @section CVSToys - PBService
3608 @csindex buildbot.changes.freshcvs.FreshCVSSource
3610 The @uref{http://purl.net/net/CVSToys, CVSToys} package provides a
3611 server which runs on the machine that hosts the CVS repository it
3612 watches. It has a variety of ways to distribute commit notifications,
3613 and offers a flexible regexp-based way to filter out uninteresting
3614 changes. One of the notification options is named @code{PBService} and
3615 works by listening on a TCP port for clients. These clients subscribe
3616 to hear about commit notifications.
3618 The buildmaster has a CVSToys-compatible @code{PBService} client built
3619 in. There are two versions of it, one for old versions of CVSToys
3620 (1.0.9 and earlier) which used the @code{oldcred} authentication
3621 framework, and one for newer versions (1.0.10 and later) which use
3622 @code{newcred}. Both are classes in the
3623 @code{buildbot.changes.freshcvs} package.
3625 @code{FreshCVSSourceNewcred} objects are created with the following
3630 @item @code{host} and @code{port}
3631 these specify where the CVSToys server can be reached
3633 @item @code{user} and @code{passwd}
3634 these specify the login information for the CVSToys server
3635 (@code{freshcvs}). These must match the server's values, which are
3636 defined in the @code{freshCfg} configuration file (which lives in the
3637 CVSROOT directory of the repository).
3640 this is the prefix to be found and stripped from filenames delivered
3641 by the CVSToys server. Most projects live in sub-directories of the
3642 main repository, as siblings of the CVSROOT sub-directory, so
3643 typically this prefix is set to that top sub-directory name.
3649 To set up the freshCVS server, add a statement like the following to
3650 your @file{freshCfg} file:
3653 pb = ConfigurationSet([
3654 (None, None, None, PBService(userpass=('foo', 'bar'), port=4519)),
3658 This will announce all changes to a client which connects to port 4519
3659 using a username of 'foo' and a password of 'bar'.
3661 Then add a clause like this to your buildmaster's @file{master.cfg}:
3664 BuildmasterConfig['change_source'] = FreshCVSSource("cvs.example.com", 4519,
3669 where "cvs.example.com" is the host that is running the FreshCVS daemon, and
3670 "glib" is the top-level directory (relative to the repository's root) where
3671 all your source code lives. Most projects keep one or more projects in the
3672 same repository (along with CVSROOT/ to hold admin files like loginfo and
3673 freshCfg); the prefix= argument tells the buildmaster to ignore everything
3674 outside that directory, and to strip that common prefix from all pathnames
3678 @node Mail-parsing ChangeSources, PBChangeSource, CVSToys - PBService, Getting Source Code Changes
3679 @section Mail-parsing ChangeSources
3681 Many projects publish information about changes to their source tree
3682 by sending an email message out to a mailing list, frequently named
3683 PROJECT-commits or PROJECT-changes. Each message usually contains a
3684 description of the change (who made the change, which files were
3685 affected) and sometimes a copy of the diff. Humans can subscribe to
3686 this list to stay informed about what's happening to the source tree.
3688 The Buildbot can also be subscribed to a -commits mailing list, and
3689 can trigger builds in response to Changes that it hears about. The
3690 buildmaster admin needs to arrange for these email messages to arrive
3691 in a place where the buildmaster can find them, and configure the
3692 buildmaster to parse the messages correctly. Once that is in place,
3693 the email parser will create Change objects and deliver them to the
3694 Schedulers (see @pxref{Change Sources and Schedulers}) just
3695 like any other ChangeSource.
3697 There are two components to setting up an email-based ChangeSource.
3698 The first is to route the email messages to the buildmaster, which is
3699 done by dropping them into a ``maildir''. The second is to actually
3700 parse the messages, which is highly dependent upon the tool that was
3701 used to create them. Each VC system has a collection of favorite
3702 change-emailing tools, and each has a slightly different format, so
3703 each has a different parsing function. There is a separate
3704 ChangeSource variant for each parsing function.
3706 Once you've chosen a maildir location and a parsing function, create
3707 the change source and put it in @code{c['change_source']}:
3710 from buildbot.changes.mail import SyncmailMaildirSource
3711 c['change_source'] = SyncmailMaildirSource("~/maildir-buildbot",
3716 * Subscribing the Buildmaster::
3718 * Parsing Email Change Messages::
3721 @node Subscribing the Buildmaster, Using Maildirs, Mail-parsing ChangeSources, Mail-parsing ChangeSources
3722 @subsection Subscribing the Buildmaster
3724 The recommended way to install the buildbot is to create a dedicated
3725 account for the buildmaster. If you do this, the account will probably
3726 have a distinct email address (perhaps
3727 @email{buildmaster@@example.org}). Then just arrange for this
3728 account's email to be delivered to a suitable maildir (described in
3731 If the buildbot does not have its own account, ``extension addresses''
3732 can be used to distinguish between email intended for the buildmaster
3733 and email intended for the rest of the account. In most modern MTAs,
3734 the e.g. @code{foo@@example.org} account has control over every email
3735 address at example.org which begins with "foo", such that email
3736 addressed to @email{account-foo@@example.org} can be delivered to a
3737 different destination than @email{account-bar@@example.org}. qmail
3738 does this by using separate .qmail files for the two destinations
3739 (@file{.qmail-foo} and @file{.qmail-bar}, with @file{.qmail}
3740 controlling the base address and @file{.qmail-default} controlling all
3741 other extensions). Other MTAs have similar mechanisms.
3743 Thus you can assign an extension address like
3744 @email{foo-buildmaster@@example.org} to the buildmaster, and retain
3745 @email{foo@@example.org} for your own use.
3748 @node Using Maildirs, Parsing Email Change Messages, Subscribing the Buildmaster, Mail-parsing ChangeSources
3749 @subsection Using Maildirs
3751 A ``maildir'' is a simple directory structure originally developed for
3752 qmail that allows safe atomic update without locking. Create a base
3753 directory with three subdirectories: ``new'', ``tmp'', and ``cur''.
3754 When messages arrive, they are put into a uniquely-named file (using
3755 pids, timestamps, and random numbers) in ``tmp''. When the file is
3756 complete, it is atomically renamed into ``new''. Eventually the
3757 buildmaster notices the file in ``new'', reads and parses the
3758 contents, then moves it into ``cur''. A cronjob can be used to delete
3759 files in ``cur'' at leisure.
3761 Maildirs are frequently created with the @command{maildirmake} tool,
3762 but a simple @command{mkdir -p ~/MAILDIR/@{cur,new,tmp@}} is pretty much
3765 Many modern MTAs can deliver directly to maildirs. The usual .forward
3766 or .procmailrc syntax is to name the base directory with a trailing
3767 slash, so something like @code{~/MAILDIR/} . qmail and postfix are
3768 maildir-capable MTAs, and procmail is a maildir-capable MDA (Mail
3771 For MTAs which cannot put files into maildirs directly, the
3772 ``safecat'' tool can be executed from a .forward file to accomplish
3775 The Buildmaster uses the linux DNotify facility to receive immediate
3776 notification when the maildir's ``new'' directory has changed. When
3777 this facility is not available, it polls the directory for new
3778 messages, every 10 seconds by default.
3780 @node Parsing Email Change Messages, , Using Maildirs, Mail-parsing ChangeSources
3781 @subsection Parsing Email Change Messages
3783 The second component to setting up an email-based ChangeSource is to
3784 parse the actual notices. This is highly dependent upon the VC system
3785 and commit script in use.
3787 A couple of common tools used to create these change emails are:
3793 @item CVSToys MailNotifier
3794 @ref{FCMaildirSource}
3795 @item Bonsai notification
3796 @ref{BonsaiMaildirSource}
3798 @ref{SyncmailMaildirSource}
3804 http://opensource.perlig.de/en/svnmailer/
3805 @item commit-email.pl
3806 @ref{SVNCommitEmailMaildirSource}
3811 @item NotifyExtension
3812 http://www.selenic.com/mercurial/wiki/index.cgi/NotifyExtension
3817 @item post-receive-email
3818 http://git.kernel.org/?p=git/git.git;a=blob;f=contrib/hooks/post-receive-email;hb=HEAD
3824 The following sections describe the parsers available for each of
3827 Most of these parsers accept a @code{prefix=} argument, which is used
3828 to limit the set of files that the buildmaster pays attention to. This
3829 is most useful for systems like CVS and SVN which put multiple
3830 projects in a single repository (or use repository names to indicate
3831 branches). Each filename that appears in the email is tested against
3832 the prefix: if the filename does not start with the prefix, the file
3833 is ignored. If the filename @emph{does} start with the prefix, that
3834 prefix is stripped from the filename before any further processing is
3835 done. Thus the prefix usually ends with a slash.
3839 * SyncmailMaildirSource::
3840 * BonsaiMaildirSource::
3841 * SVNCommitEmailMaildirSource::
3844 @node FCMaildirSource, SyncmailMaildirSource, Parsing Email Change Messages, Parsing Email Change Messages
3845 @subsubsection FCMaildirSource
3848 @csindex buildbot.changes.mail.FCMaildirSource
3850 http://twistedmatrix.com/users/acapnotic/wares/code/CVSToys/
3852 This parser works with the CVSToys @code{MailNotification} action,
3853 which will send email to a list of recipients for each commit. This
3854 tends to work better than using @code{/bin/mail} from within the
3855 CVSROOT/loginfo file directly, as CVSToys will batch together all
3856 files changed during the same CVS invocation, and can provide more
3857 information (like creating a ViewCVS URL for each file changed).
3859 The Buildbot's @code{FCMaildirSource} knows for to parse these CVSToys
3860 messages and turn them into Change objects. It can be given two
3861 parameters: the directory name of the maildir root, and the prefix to
3865 from buildbot.changes.mail import FCMaildirSource
3866 c['change_source'] = FCMaildirSource("~/maildir-buildbot")
3869 @node SyncmailMaildirSource, BonsaiMaildirSource, FCMaildirSource, Parsing Email Change Messages
3870 @subsubsection SyncmailMaildirSource
3872 @csindex buildbot.changes.mail.SyncmailMaildirSource
3874 http://sourceforge.net/projects/cvs-syncmail
3876 @code{SyncmailMaildirSource} knows how to parse the message format used by
3877 the CVS ``syncmail'' script.
3880 from buildbot.changes.mail import SyncmailMaildirSource
3881 c['change_source'] = SyncmailMaildirSource("~/maildir-buildbot")
3884 @node BonsaiMaildirSource, SVNCommitEmailMaildirSource, SyncmailMaildirSource, Parsing Email Change Messages
3885 @subsubsection BonsaiMaildirSource
3887 @csindex buildbot.changes.mail.BonsaiMaildirSource
3889 http://www.mozilla.org/bonsai.html
3891 @code{BonsaiMaildirSource} parses messages sent out by Bonsai, the CVS
3892 tree-management system built by Mozilla.
3895 from buildbot.changes.mail import BonsaiMaildirSource
3896 c['change_source'] = BonsaiMaildirSource("~/maildir-buildbot")
3899 @node SVNCommitEmailMaildirSource, , BonsaiMaildirSource, Parsing Email Change Messages
3900 @subsubsection SVNCommitEmailMaildirSource
3902 @csindex buildbot.changes.mail.SVNCommitEmailMaildirSource
3904 @code{SVNCommitEmailMaildirSource} parses message sent out by the
3905 @code{commit-email.pl} script, which is included in the Subversion
3908 It does not currently handle branches: all of the Change objects that
3909 it creates will be associated with the default (i.e. trunk) branch.
3912 from buildbot.changes.mail import SVNCommitEmailMaildirSource
3913 c['change_source'] = SVNCommitEmailMaildirSource("~/maildir-buildbot")
3917 @node PBChangeSource, P4Source, Mail-parsing ChangeSources, Getting Source Code Changes
3918 @section PBChangeSource
3920 @csindex buildbot.changes.pb.PBChangeSource
3922 The last kind of ChangeSource actually listens on a TCP port for
3923 clients to connect and push change notices @emph{into} the
3924 Buildmaster. This is used by the built-in @code{buildbot sendchange}
3925 notification tool, as well as the VC-specific
3926 @file{contrib/svn_buildbot.py}, @file{contrib/arch_buildbot.py},
3927 @file{contrib/hg_buildbot.py} tools, and the
3928 @code{buildbot.changes.hgbuildbot} hook. These tools are run by the
3929 repository (in a commit hook script), and connect to the buildmaster
3930 directly each time a file is comitted. This is also useful for
3931 creating new kinds of change sources that work on a @code{push} model
3932 instead of some kind of subscription scheme, for example a script
3933 which is run out of an email .forward file.
3935 This ChangeSource can be configured to listen on its own TCP port, or
3936 it can share the port that the buildmaster is already using for the
3937 buildslaves to connect. (This is possible because the
3938 @code{PBChangeSource} uses the same protocol as the buildslaves, and
3939 they can be distinguished by the @code{username} attribute used when
3940 the initial connection is established). It might be useful to have it
3941 listen on a different port if, for example, you wanted to establish
3942 different firewall rules for that port. You could allow only the SVN
3943 repository machine access to the @code{PBChangeSource} port, while
3944 allowing only the buildslave machines access to the slave port. Or you
3945 could just expose one port and run everything over it. @emph{Note:
3946 this feature is not yet implemented, the PBChangeSource will always
3947 share the slave port and will always have a @code{user} name of
3948 @code{change}, and a passwd of @code{changepw}. These limitations will
3949 be removed in the future.}.
3952 The @code{PBChangeSource} is created with the following arguments. All
3957 which port to listen on. If @code{None} (which is the default), it
3958 shares the port used for buildslave connections. @emph{Not
3959 Implemented, always set to @code{None}}.
3961 @item @code{user} and @code{passwd}
3962 The user/passwd account information that the client program must use
3963 to connect. Defaults to @code{change} and @code{changepw}. @emph{Not
3964 Implemented, @code{user} is currently always set to @code{change},
3965 @code{passwd} is always set to @code{changepw}}.
3968 The prefix to be found and stripped from filenames delivered over the
3969 connection. Any filenames which do not start with this prefix will be
3970 removed. If all the filenames in a given Change are removed, the that
3971 whole Change will be dropped. This string should probably end with a
3972 directory separator.
3974 This is useful for changes coming from version control systems that
3975 represent branches as parent directories within the repository (like
3976 SVN and Perforce). Use a prefix of 'trunk/' or
3977 'project/branches/foobranch/' to only follow one branch and to get
3978 correct tree-relative filenames. Without a prefix, the PBChangeSource
3979 will probably deliver Changes with filenames like @file{trunk/foo.c}
3980 instead of just @file{foo.c}. Of course this also depends upon the
3981 tool sending the Changes in (like @command{buildbot sendchange}) and
3982 what filenames it is delivering: that tool may be filtering and
3983 stripping prefixes at the sending end.
3987 @node P4Source, BonsaiPoller, PBChangeSource, Getting Source Code Changes
3990 @csindex buildbot.changes.p4poller.P4Source
3992 The @code{P4Source} periodically polls a @uref{http://www.perforce.com/,
3993 Perforce} depot for changes. It accepts the following arguments:
3997 The base depot path to watch, without the trailing '/...'.
4000 The Perforce server to connect to (as host:port).
4005 @item @code{p4passwd}
4006 The Perforce password.
4009 An optional string parameter. Specify the location of the perforce command
4010 line binary (p4). You only need to do this if the perforce binary is not
4011 in the path of the buildbot user. Defaults to ``p4''.
4013 @item @code{split_file}
4014 A function that maps a pathname, without the leading @code{p4base}, to a
4015 (branch, filename) tuple. The default just returns (None, branchfile),
4016 which effectively disables branch support. You should supply a function
4017 which understands your repository structure.
4019 @item @code{pollinterval}
4020 How often to poll, in seconds. Defaults to 600 (10 minutes).
4022 @item @code{histmax}
4023 The maximum number of changes to inspect at a time. If more than this
4024 number occur since the last poll, older changes will be silently
4030 This configuration uses the @code{P4PORT}, @code{P4USER}, and @code{P4PASSWD}
4031 specified in the buildmaster's environment. It watches a project in which the
4032 branch name is simply the next path component, and the file is all path
4036 import buildbot.changes.p4poller
4037 s = p4poller.P4Source(p4base='//depot/project/',
4038 split_file=lambda branchfile: branchfile.split('/',1),
4040 c['change_source'] = s
4043 @node BonsaiPoller, SVNPoller, P4Source, Getting Source Code Changes
4044 @section BonsaiPoller
4046 @csindex buildbot.changes.bonsaipoller.BonsaiPoller
4048 The @code{BonsaiPoller} periodically polls a Bonsai server. This is a
4049 CGI script accessed through a web server that provides information
4050 about a CVS tree, for example the Mozilla bonsai server at
4051 @uref{http://bonsai.mozilla.org}. Bonsai servers are usable by both
4052 humans and machines. In this case, the buildbot's change source forms
4053 a query which asks about any files in the specified branch which have
4054 changed since the last query.
4056 Please take a look at the BonsaiPoller docstring for details about the
4057 arguments it accepts.
4060 @node SVNPoller, MercurialHook, BonsaiPoller, Getting Source Code Changes
4063 @csindex buildbot.changes.svnpoller.SVNPoller
4065 The @code{buildbot.changes.svnpoller.SVNPoller} is a ChangeSource
4066 which periodically polls a @uref{http://subversion.tigris.org/,
4067 Subversion} repository for new revisions, by running the @code{svn
4068 log} command in a subshell. It can watch a single branch or multiple
4071 @code{SVNPoller} accepts the following arguments:
4075 The base URL path to watch, like
4076 @code{svn://svn.twistedmatrix.com/svn/Twisted/trunk}, or
4077 @code{http://divmod.org/svn/Divmod/}, or even
4078 @code{file:///home/svn/Repository/ProjectA/branches/1.5/}. This must
4079 include the access scheme, the location of the repository (both the
4080 hostname for remote ones, and any additional directory names necessary
4081 to get to the repository), and the sub-path within the repository's
4082 virtual filesystem for the project and branch of interest.
4084 The @code{SVNPoller} will only pay attention to files inside the
4085 subdirectory specified by the complete svnurl.
4088 A function to convert pathnames into (branch, relative_pathname)
4089 tuples. Use this to explain your repository's branch-naming policy to
4090 @code{SVNPoller}. This function must accept a single string and return
4091 a two-entry tuple. There are a few utility functions in
4092 @code{buildbot.changes.svnpoller} that can be used as a
4093 @code{split_file} function, see below for details.
4095 The default value always returns (None, path), which indicates that
4096 all files are on the trunk.
4098 Subclasses of @code{SVNPoller} can override the @code{split_file}
4099 method instead of using the @code{split_file=} argument.
4102 An optional string parameter. If set, the @code{--user} argument will
4103 be added to all @code{svn} commands. Use this if you have to
4104 authenticate to the svn server before you can do @code{svn info} or
4105 @code{svn log} commands.
4108 Like @code{svnuser}, this will cause a @code{--password} argument to
4109 be passed to all svn commands.
4112 How often to poll, in seconds. Defaults to 600 (checking once every 10
4113 minutes). Lower this if you want the buildbot to notice changes
4114 faster, raise it if you want to reduce the network and CPU load on
4115 your svn server. Please be considerate of public SVN repositories by
4116 using a large interval when polling them.
4119 The maximum number of changes to inspect at a time. Every POLLINTERVAL
4120 seconds, the @code{SVNPoller} asks for the last HISTMAX changes and
4121 looks through them for any ones it does not already know about. If
4122 more than HISTMAX revisions have been committed since the last poll,
4123 older changes will be silently ignored. Larger values of histmax will
4124 cause more time and memory to be consumed on each poll attempt.
4125 @code{histmax} defaults to 100.
4128 This controls the @code{svn} executable to use. If subversion is
4129 installed in a weird place on your system (outside of the
4130 buildmaster's @code{$PATH}), use this to tell @code{SVNPoller} where
4131 to find it. The default value of ``svn'' will almost always be
4138 Each source file that is tracked by a Subversion repository has a
4139 fully-qualified SVN URL in the following form:
4140 (REPOURL)(PROJECT-plus-BRANCH)(FILEPATH). When you create the
4141 @code{SVNPoller}, you give it a @code{svnurl} value that includes all
4142 of the REPOURL and possibly some portion of the PROJECT-plus-BRANCH
4143 string. The @code{SVNPoller} is responsible for producing Changes that
4144 contain a branch name and a FILEPATH (which is relative to the top of
4145 a checked-out tree). The details of how these strings are split up
4146 depend upon how your repository names its branches.
4148 @subheading PROJECT/BRANCHNAME/FILEPATH repositories
4150 One common layout is to have all the various projects that share a
4151 repository get a single top-level directory each. Then under a given
4152 project's directory, you get two subdirectories, one named ``trunk''
4153 and another named ``branches''. Under ``branches'' you have a bunch of
4154 other directories, one per branch, with names like ``1.5.x'' and
4155 ``testing''. It is also common to see directories like ``tags'' and
4156 ``releases'' next to ``branches'' and ``trunk''.
4158 For example, the Twisted project has a subversion server on
4159 ``svn.twistedmatrix.com'' that hosts several sub-projects. The
4160 repository is available through a SCHEME of ``svn:''. The primary
4161 sub-project is Twisted, of course, with a repository root of
4162 ``svn://svn.twistedmatrix.com/svn/Twisted''. Another sub-project is
4163 Informant, with a root of
4164 ``svn://svn.twistedmatrix.com/svn/Informant'', etc. Inside any
4165 checked-out Twisted tree, there is a file named bin/trial (which is
4166 used to run unit test suites).
4168 The trunk for Twisted is in
4169 ``svn://svn.twistedmatrix.com/svn/Twisted/trunk'', and the
4170 fully-qualified SVN URL for the trunk version of @code{trial} would be
4171 ``svn://svn.twistedmatrix.com/svn/Twisted/trunk/bin/trial''. The same
4172 SVNURL for that file on a branch named ``1.5.x'' would be
4173 ``svn://svn.twistedmatrix.com/svn/Twisted/branches/1.5.x/bin/trial''.
4175 To set up a @code{SVNPoller} that watches the Twisted trunk (and
4176 nothing else), we would use the following:
4179 from buildbot.changes.svnpoller import SVNPoller
4180 c['change_source'] = SVNPoller("svn://svn.twistedmatrix.com/svn/Twisted/trunk")
4183 In this case, every Change that our @code{SVNPoller} produces will
4184 have @code{.branch=None}, to indicate that the Change is on the trunk.
4185 No other sub-projects or branches will be tracked.
4187 If we want our ChangeSource to follow multiple branches, we have to do
4188 two things. First we have to change our @code{svnurl=} argument to
4189 watch more than just ``.../Twisted/trunk''. We will set it to
4190 ``.../Twisted'' so that we'll see both the trunk and all the branches.
4191 Second, we have to tell @code{SVNPoller} how to split the
4192 (PROJECT-plus-BRANCH)(FILEPATH) strings it gets from the repository
4193 out into (BRANCH) and (FILEPATH) pairs.
4195 We do the latter by providing a ``split_file'' function. This function
4196 is responsible for splitting something like
4197 ``branches/1.5.x/bin/trial'' into @code{branch}=''branches/1.5.x'' and
4198 @code{filepath}=''bin/trial''. This function is always given a string
4199 that names a file relative to the subdirectory pointed to by the
4200 @code{SVNPoller}'s @code{svnurl=} argument. It is expected to return a
4201 (BRANCHNAME, FILEPATH) tuple (in which FILEPATH is relative to the
4202 branch indicated), or None to indicate that the file is outside any
4203 project of interest.
4205 (note that we want to see ``branches/1.5.x'' rather than just
4206 ``1.5.x'' because when we perform the SVN checkout, we will probably
4207 append the branch name to the baseURL, which requires that we keep the
4208 ``branches'' component in there. Other VC schemes use a different
4209 approach towards branches and may not require this artifact.)
4211 If your repository uses this same PROJECT/BRANCH/FILEPATH naming
4212 scheme, the following function will work:
4215 def split_file_branches(path):
4216 pieces = path.split('/')
4217 if pieces[0] == 'trunk':
4218 return (None, '/'.join(pieces[1:]))
4219 elif pieces[0] == 'branches':
4220 return ('/'.join(pieces[0:2]),
4221 '/'.join(pieces[2:]))
4226 This function is provided as
4227 @code{buildbot.changes.svnpoller.split_file_branches} for your
4228 convenience. So to have our Twisted-watching @code{SVNPoller} follow
4229 multiple branches, we would use this:
4232 from buildbot.changes.svnpoller import SVNPoller, split_file_branches
4233 c['change_source'] = SVNPoller("svn://svn.twistedmatrix.com/svn/Twisted",
4234 split_file=split_file_branches)
4237 Changes for all sorts of branches (with names like ``branches/1.5.x'',
4238 and None to indicate the trunk) will be delivered to the Schedulers.
4239 Each Scheduler is then free to use or ignore each branch as it sees
4242 @subheading BRANCHNAME/PROJECT/FILEPATH repositories
4244 Another common way to organize a Subversion repository is to put the
4245 branch name at the top, and the projects underneath. This is
4246 especially frequent when there are a number of related sub-projects
4247 that all get released in a group.
4249 For example, Divmod.org hosts a project named ``Nevow'' as well as one
4250 named ``Quotient''. In a checked-out Nevow tree there is a directory
4251 named ``formless'' that contains a python source file named
4252 ``webform.py''. This repository is accessible via webdav (and thus
4253 uses an ``http:'' scheme) through the divmod.org hostname. There are
4254 many branches in this repository, and they use a
4255 (BRANCHNAME)/(PROJECT) naming policy.
4257 The fully-qualified SVN URL for the trunk version of webform.py is
4258 @code{http://divmod.org/svn/Divmod/trunk/Nevow/formless/webform.py}.
4259 You can do an @code{svn co} with that URL and get a copy of the latest
4260 version. The 1.5.x branch version of this file would have a URL of
4261 @code{http://divmod.org/svn/Divmod/branches/1.5.x/Nevow/formless/webform.py}.
4262 The whole Nevow trunk would be checked out with
4263 @code{http://divmod.org/svn/Divmod/trunk/Nevow}, while the Quotient
4264 trunk would be checked out using
4265 @code{http://divmod.org/svn/Divmod/trunk/Quotient}.
4267 Now suppose we want to have an @code{SVNPoller} that only cares about
4268 the Nevow trunk. This case looks just like the PROJECT/BRANCH layout
4272 from buildbot.changes.svnpoller import SVNPoller
4273 c['change_source'] = SVNPoller("http://divmod.org/svn/Divmod/trunk/Nevow")
4276 But what happens when we want to track multiple Nevow branches? We
4277 have to point our @code{svnurl=} high enough to see all those
4278 branches, but we also don't want to include Quotient changes (since
4279 we're only building Nevow). To accomplish this, we must rely upon the
4280 @code{split_file} function to help us tell the difference between
4281 files that belong to Nevow and those that belong to Quotient, as well
4282 as figuring out which branch each one is on.
4285 from buildbot.changes.svnpoller import SVNPoller
4286 c['change_source'] = SVNPoller("http://divmod.org/svn/Divmod",
4287 split_file=my_file_splitter)
4290 The @code{my_file_splitter} function will be called with
4291 repository-relative pathnames like:
4294 @item trunk/Nevow/formless/webform.py
4295 This is a Nevow file, on the trunk. We want the Change that includes this
4296 to see a filename of @code{formless/webform.py"}, and a branch of None
4298 @item branches/1.5.x/Nevow/formless/webform.py
4299 This is a Nevow file, on a branch. We want to get
4300 branch=''branches/1.5.x'' and filename=''formless/webform.py''.
4302 @item trunk/Quotient/setup.py
4303 This is a Quotient file, so we want to ignore it by having
4304 @code{my_file_splitter} return None.
4306 @item branches/1.5.x/Quotient/setup.py
4307 This is also a Quotient file, which should be ignored.
4310 The following definition for @code{my_file_splitter} will do the job:
4313 def my_file_splitter(path):
4314 pieces = path.split('/')
4315 if pieces[0] == 'trunk':
4317 pieces.pop(0) # remove 'trunk'
4318 elif pieces[0] == 'branches':
4319 pieces.pop(0) # remove 'branches'
4321 branch = 'branches/' + pieces.pop(0)
4323 return None # something weird
4324 projectname = pieces.pop(0)
4325 if projectname != 'Nevow':
4326 return None # wrong project
4327 return (branch, '/'.join(pieces))
4330 @node MercurialHook, Bzr Hook, SVNPoller, Getting Source Code Changes
4331 @section MercurialHook
4333 Since Mercurial is written in python, the hook script can invoke
4334 Buildbot's @code{sendchange} function directly, rather than having to
4335 spawn an external process. This function delivers the same sort of
4336 changes as @code{buildbot sendchange} and the various hook scripts in
4337 contrib/, so you'll need to add a @code{pb.PBChangeSource} to your
4338 buildmaster to receive these changes.
4340 To set this up, first choose a Mercurial repository that represents
4341 your central ``official'' source tree. This will be the same
4342 repository that your buildslaves will eventually pull from. Install
4343 Buildbot on the machine that hosts this repository, using the same
4344 version of python as Mercurial is using (so that the Mercurial hook
4345 can import code from buildbot). Then add the following to the
4346 @code{.hg/hgrc} file in that repository, replacing the buildmaster
4347 hostname/portnumber as appropriate for your buildbot:
4351 changegroup.buildbot = python:buildbot.changes.hgbuildbot.hook
4354 master = buildmaster.example.org:9987
4357 (Note that Mercurial lets you define multiple @code{changegroup} hooks
4358 by giving them distinct names, like @code{changegroup.foo} and
4359 @code{changegroup.bar}, which is why we use
4360 @code{changegroup.buildbot} in this example. There is nothing magical
4361 about the ``buildbot'' suffix in the hook name. The
4362 @code{[hgbuildbot]} section @emph{is} special, however, as it is the
4363 only section that the buildbot hook pays attention to.)
4365 Also note that this runs as a @code{changegroup} hook, rather than as
4366 an @code{incoming} hook. The @code{changegroup} hook is run with
4367 multiple revisions at a time (say, if multiple revisions are being
4368 pushed to this repository in a single @command{hg push} command),
4369 whereas the @code{incoming} hook is run with just one revision at a
4370 time. The @code{hgbuildbot.hook} function will only work with the
4371 @code{changegroup} hook.
4373 The @code{[hgbuildbot]} section has two other parameters that you
4374 might specify, both of which control the name of the branch that is
4375 attached to the changes coming from this hook.
4377 One common branch naming policy for Mercurial repositories is to use
4378 it just like Darcs: each branch goes into a separate repository, and
4379 all the branches for a single project share a common parent directory.
4380 For example, you might have @file{/var/repos/PROJECT/trunk/} and
4381 @file{/var/repos/PROJECT/release}. To use this style, use the
4382 @code{branchtype = dirname} setting, which simply uses the last
4383 component of the repository's enclosing directory as the branch name:
4387 master = buildmaster.example.org:9987
4388 branchtype = dirname
4391 Another approach is to use Mercurial's built-in branches (the kind
4392 created with @command{hg branch} and listed with @command{hg
4393 branches}). This feature associates persistent names with particular
4394 lines of descent within a single repository. (note that the buildbot
4395 @code{source.Mercurial} checkout step does not yet support this kind
4396 of branch). To have the commit hook deliver this sort of branch name
4397 with the Change object, use @code{branchtype = inrepo}:
4401 master = buildmaster.example.org:9987
4405 Finally, if you want to simply specify the branchname directly, for
4406 all changes, use @code{branch = BRANCHNAME}. This overrides
4411 master = buildmaster.example.org:9987
4415 If you use @code{branch=} like this, you'll need to put a separate
4416 .hgrc in each repository. If you use @code{branchtype=}, you may be
4417 able to use the same .hgrc for all your repositories, stored in
4418 @file{~/.hgrc} or @file{/etc/mercurial/hgrc}.
4421 @node Bzr Hook, Bzr Poller, MercurialHook, Getting Source Code Changes
4424 Bzr is also written in Python, and the Bzr hook depends on Twisted to send the
4427 To install, put @code{contrib/bzr_buildbot.py} in one of your plugins
4428 locations a bzr plugins directory (e.g.,
4429 @code{~/.bazaar/plugins}). Then, in one of your bazaar conf files (e.g.,
4430 @code{~/.bazaar/locations.conf}), set the location you want to connect with buildbot
4435 one of 'commit', 'push, or 'change'. Turns the plugin on to report changes via
4436 commit, changes via push, or any changes to the trunk. 'change' is
4439 @item buildbot_server
4440 (required to send to a buildbot master) the URL of the buildbot master to
4441 which you will connect (as of this writing, the same server and port to which
4445 (optional, defaults to 9989) the port of the buildbot master to which you will
4446 connect (as of this writing, the same server and port to which slaves connect)
4449 (optional, defaults to not pqm) Normally, the user that commits the revision
4450 is the user that is responsible for the change. When run in a pqm (Patch Queue
4451 Manager, see https://launchpad.net/pqm) environment, the user that commits is
4452 the Patch Queue Manager, and the user that committed the *parent* revision is
4453 responsible for the change. To turn on the pqm mode, set this value to any of
4454 (case-insensitive) "Yes", "Y", "True", or "T".
4456 @item buildbot_dry_run
4457 (optional, defaults to not a dry run) Normally, the post-commit hook will
4458 attempt to communicate with the configured buildbot server and port. If this
4459 parameter is included and any of (case-insensitive) "Yes", "Y", "True", or
4460 "T", then the hook will simply print what it would have sent, but not attempt
4461 to contact the buildbot master.
4463 @item buildbot_send_branch_name
4464 (optional, defaults to not sending the branch name) If your buildbot's bzr
4465 source build step uses a repourl, do *not* turn this on. If your buildbot's
4466 bzr build step uses a baseURL, then you may set this value to any of
4467 (case-insensitive) "Yes", "Y", "True", or "T" to have the buildbot master
4468 append the branch name to the baseURL.
4472 When buildbot no longer has a hardcoded password, it will be a configuration
4473 option here as well.
4475 Here's a simple example that you might have in your
4476 @code{~/.bazaar/locations.conf}.
4479 [chroot-*:///var/local/myrepo/mybranch]
4480 buildbot_on = change
4481 buildbot_server = localhost
4484 @node Bzr Poller, , Bzr Hook, Getting Source Code Changes
4487 If you cannot insert a Bzr hook in the server, you can use the Bzr Poller. To
4488 use, put @code{contrib/bzr_buildbot.py} somewhere that your buildbot
4489 configuration can import it. Even putting it in the same directory as the master.cfg
4490 should work. Install the poller in the buildbot configuration as with any
4491 other change source. Minimally, provide a URL that you want to poll (bzr://,
4492 bzr+ssh://, or lp:), though make sure the buildbot user has necessary
4493 privileges. You may also want to specify these optional values.
4497 The number of seconds to wait between polls. Defaults to 10 minutes.
4500 Any value to be used as the branch name. Defaults to None, or specify a
4501 string, or specify the constants from @code{bzr_buildbot.py} SHORT or FULL to
4502 get the short branch name or full branch address.
4504 @item blame_merge_author
4505 normally, the user that commits the revision is the user that is responsible
4506 for the change. When run in a pqm (Patch Queue Manager, see
4507 https://launchpad.net/pqm) environment, the user that commits is the Patch
4508 Queue Manager, and the user that committed the merged, *parent* revision is
4509 responsible for the change. set this value to True if this is pointed against
4510 a PQM-managed branch.
4513 @node Build Process, Status Delivery, Getting Source Code Changes, Top
4514 @chapter Build Process
4516 A @code{Build} object is responsible for actually performing a build.
4517 It gets access to a remote @code{SlaveBuilder} where it may run
4518 commands, and a @code{BuildStatus} object where it must emit status
4519 events. The @code{Build} is created by the Builder's
4520 @code{BuildFactory}.
4522 The default @code{Build} class is made up of a fixed sequence of
4523 @code{BuildSteps}, executed one after another until all are complete
4524 (or one of them indicates that the build should be halted early). The
4525 default @code{BuildFactory} creates instances of this @code{Build}
4526 class with a list of @code{BuildSteps}, so the basic way to configure
4527 the build is to provide a list of @code{BuildSteps} to your
4528 @code{BuildFactory}.
4530 More complicated @code{Build} subclasses can make other decisions:
4531 execute some steps only if certain files were changed, or if certain
4532 previous steps passed or failed. The base class has been written to
4533 allow users to express basic control flow without writing code, but
4534 you can always subclass and customize to achieve more specialized
4543 @node Build Steps, Interlocks, Build Process, Build Process
4544 @section Build Steps
4546 @code{BuildStep}s are usually specified in the buildmaster's
4547 configuration file, in a list that goes into the @code{BuildFactory}.
4548 The @code{BuildStep} instances in this list are used as templates to
4549 construct new independent copies for each build (so that state can be
4550 kept on the @code{BuildStep} in one build without affecting a later
4551 build). Each @code{BuildFactory} can be created with a list of steps,
4552 or the factory can be created empty and then steps added to it using
4553 the @code{addStep} method:
4556 from buildbot.steps import source, shell
4557 from buildbot.process import factory
4559 f = factory.BuildFactory()
4560 f.addStep(source.SVN(svnurl="http://svn.example.org/Trunk/"))
4561 f.addStep(shell.ShellCommand(command=["make", "all"]))
4562 f.addStep(shell.ShellCommand(command=["make", "test"]))
4565 In earlier versions (0.7.5 and older), these steps were specified with
4566 a tuple of (step_class, keyword_arguments). Steps can still be
4567 specified this way, but the preferred form is to pass actual
4568 @code{BuildStep} instances to @code{addStep}, because that gives the
4569 @code{BuildStep} class a chance to do some validation on the
4572 If you have a common set of steps which are used in several factories, the
4573 @code{addSteps} method may be handy. It takes an iterable of @code{BuildStep}
4578 source.SVN(svnurl="http://svn.example.org/Trunk/")
4579 shell.ShellCommand(command="./setup")
4581 quick = factory.BuildFactory()
4582 quick.addSteps(setup_steps)
4583 quick.addStep(shell.shellCommand(command="make quick"))
4586 The rest of this section lists all the standard BuildStep objects
4587 available for use in a Build, and the parameters which can be used to
4591 * Common Parameters::
4592 * Using Build Properties::
4595 * Simple ShellCommand Subclasses::
4596 * Python BuildSteps::
4597 * Transferring Files::
4598 * Steps That Run on the Master::
4599 * Triggering Schedulers::
4600 * Writing New BuildSteps::
4603 @node Common Parameters, Using Build Properties, Build Steps, Build Steps
4604 @subsection Common Parameters
4606 The standard @code{Build} runs a series of @code{BuildStep}s in order,
4607 only stopping when it runs out of steps or if one of them requests
4608 that the build be halted. It collects status information from each one
4609 to create an overall build status (of SUCCESS, WARNINGS, or FAILURE).
4611 All BuildSteps accept some common parameters. Some of these control
4612 how their individual status affects the overall build. Others are used
4613 to specify which @code{Locks} (see @pxref{Interlocks}) should be
4614 acquired before allowing the step to run.
4616 Arguments common to all @code{BuildStep} subclasses:
4621 the name used to describe the step on the status display. It is also
4622 used to give a name to any LogFiles created by this step.
4625 if True, a FAILURE of this build step will cause the build to halt
4626 immediately. Steps with @code{alwaysRun=True} are still run. Generally
4627 speaking, haltOnFailure implies flunkOnFailure (the default for most
4628 BuildSteps). In some cases, particularly series of tests, it makes sense
4629 to haltOnFailure if something fails early on but not flunkOnFailure.
4630 This can be achieved with haltOnFailure=True, flunkOnFailure=False.
4632 @item flunkOnWarnings
4633 when True, a WARNINGS or FAILURE of this build step will mark the
4634 overall build as FAILURE. The remaining steps will still be executed.
4636 @item flunkOnFailure
4637 when True, a FAILURE of this build step will mark the overall build as
4638 a FAILURE. The remaining steps will still be executed.
4640 @item warnOnWarnings
4641 when True, a WARNINGS or FAILURE of this build step will mark the
4642 overall build as having WARNINGS. The remaining steps will still be
4646 when True, a FAILURE of this build step will mark the overall build as
4647 having WARNINGS. The remaining steps will still be executed.
4650 if True, this build step will always be run, even if a previous buildstep
4651 with @code{haltOnFailure=True} has failed.
4654 a list of Locks (instances of @code{buildbot.locks.SlaveLock} or
4655 @code{buildbot.locks.MasterLock}) that should be acquired before
4656 starting this Step. The Locks will be released when the step is
4657 complete. Note that this is a list of actual Lock instances, not
4658 names. Also note that all Locks must have unique names.
4662 @node Using Build Properties, Source Checkout, Common Parameters, Build Steps
4663 @subsection Using Build Properties
4666 Build properties are a generalized way to provide configuration
4667 information to build steps; see @ref{Build Properties}.
4669 Some build properties are inherited from external sources -- global
4670 properties, schedulers, or buildslaves. Some build properties are
4671 set when the build starts, such as the SourceStamp information. Other
4672 properties can be set by BuildSteps as they run, for example the
4673 various Source steps will set the @code{got_revision} property to the
4674 source revision that was actually checked out (which can be useful
4675 when the SourceStamp in use merely requested the ``latest revision'':
4676 @code{got_revision} will tell you what was actually built).
4678 In custom BuildSteps, you can get and set the build properties with
4679 the @code{getProperty}/@code{setProperty} methods. Each takes a string
4680 for the name of the property, and returns or accepts an
4681 arbitrary@footnote{Build properties are serialized along with the
4682 build results, so they must be serializable. For this reason, the
4683 value of any build property should be simple inert data: strings,
4684 numbers, lists, tuples, and dictionaries. They should not contain
4685 class instances.} object. For example:
4688 class MakeTarball(ShellCommand):
4690 if self.getProperty("os") == "win":
4691 self.setCommand([ ... ]) # windows-only command
4693 self.setCommand([ ... ]) # equivalent for other systems
4694 ShellCommand.start(self)
4697 @heading WithProperties
4698 @cindex WithProperties
4700 You can use build properties in ShellCommands by using the
4701 @code{WithProperties} wrapper when setting the arguments of
4702 the ShellCommand. This interpolates the named build properties
4703 into the generated shell command. Most step parameters accept
4704 @code{WithProperties}. Please file bugs for any parameters which
4708 from buildbot.steps.shell import ShellCommand
4709 from buildbot.process.properties import WithProperties
4711 f.addStep(ShellCommand(
4712 command=["tar", "czf",
4713 WithProperties("build-%s.tar.gz", "revision"),
4717 If this BuildStep were used in a tree obtained from Subversion, it
4718 would create a tarball with a name like @file{build-1234.tar.gz}.
4720 The @code{WithProperties} function does @code{printf}-style string
4721 interpolation, using strings obtained by calling
4722 @code{build.getProperty(propname)}. Note that for every @code{%s} (or
4723 @code{%d}, etc), you must have exactly one additional argument to
4724 indicate which build property you want to insert.
4726 You can also use python dictionary-style string interpolation by using
4727 the @code{%(propname)s} syntax. In this form, the property name goes
4728 in the parentheses, and WithProperties takes @emph{no} additional
4732 f.addStep(ShellCommand(
4733 command=["tar", "czf",
4734 WithProperties("build-%(revision)s.tar.gz"),
4738 Don't forget the extra ``s'' after the closing parenthesis! This is
4739 the cause of many confusing errors.
4741 The dictionary-style interpolation supports a number of more advanced
4746 @item propname:-replacement
4747 If @code{propname} exists, substitute its value; otherwise,
4748 substitute @code{replacement}. @code{replacement} may be empty
4749 (@code{%(propname:-)s})
4751 @item propname:+replacement
4752 If @code{propname} exists, substitute @code{replacement}; otherwise,
4753 substitute an empty string.
4757 Although these are similar to shell substitutions, no other
4758 substitutions are currently supported, and @code{replacement} in the
4759 above cannot contain more substitutions.
4761 Note: like python, you can either do positional-argument interpolation
4762 @emph{or} keyword-argument interpolation, not both. Thus you cannot use
4763 a string like @code{WithProperties("foo-%(revision)s-%s", "branch")}.
4765 @heading Common Build Properties
4767 The following build properties are set when the build is started, and
4768 are available to all steps.
4773 This comes from the build's SourceStamp, and describes which branch is
4774 being checked out. This will be @code{None} (which interpolates into
4775 @code{WithProperties} as an empty string) if the build is on the
4776 default branch, which is generally the trunk. Otherwise it will be a
4777 string like ``branches/beta1.4''. The exact syntax depends upon the VC
4782 This also comes from the SourceStamp, and is the revision of the source code
4783 tree that was requested from the VC system. When a build is requested of a
4784 specific revision (as is generally the case when the build is triggered by
4785 Changes), this will contain the revision specification. This is always a
4786 string, although the syntax depends upon the VC system in use: for SVN it is an
4787 integer, for Mercurial it is a short string, for Darcs it is a rather large
4790 If the ``force build'' button was pressed, the revision will be @code{None},
4791 which means to use the most recent revision available. This is a ``trunk
4792 build''. This will be interpolated as an empty string.
4796 This is set when a Source step checks out the source tree, and
4797 provides the revision that was actually obtained from the VC system.
4798 In general this should be the same as @code{revision}, except for
4799 trunk builds, where @code{got_revision} indicates what revision was
4800 current when the checkout was performed. This can be used to rebuild
4801 the same source code later.
4803 Note that for some VC systems (Darcs in particular), the revision is a
4804 large string containing newlines, and is not suitable for interpolation
4809 This is a string that indicates which Builder the build was a part of.
4810 The combination of buildername and buildnumber uniquely identify a
4815 Each build gets a number, scoped to the Builder (so the first build
4816 performed on any given Builder will have a build number of 0). This
4817 integer property contains the build's number.
4821 This is a string which identifies which buildslave the build is
4826 If the build was started from a scheduler, then this property will
4827 contain the name of that scheduler.
4832 @node Source Checkout, ShellCommand, Using Build Properties, Build Steps
4833 @subsection Source Checkout
4835 The first step of any build is typically to acquire the source code
4836 from which the build will be performed. There are several classes to
4837 handle this, one for each of the different source control system that
4838 Buildbot knows about. For a description of how Buildbot treats source
4839 control in general, see @ref{Version Control Systems}.
4841 All source checkout steps accept some common parameters to control how
4842 they get the sources and where they should be placed. The remaining
4843 per-VC-system parameters are mostly to specify where exactly the
4844 sources are coming from.
4849 a string describing the kind of VC operation that is desired. Defaults
4854 specifies that the CVS checkout/update should be performed directly
4855 into the workdir. Each build is performed in the same directory,
4856 allowing for incremental builds. This minimizes disk space, bandwidth,
4857 and CPU time. However, it may encounter problems if the build process
4858 does not handle dependencies properly (sometimes you must do a ``clean
4859 build'' to make sure everything gets compiled), or if source files are
4860 deleted but generated files can influence test behavior (e.g. python's
4861 .pyc files), or when source directories are deleted but generated
4862 files prevent CVS from removing them. Builds ought to be correct
4863 regardless of whether they are done ``from scratch'' or incrementally,
4864 but it is useful to test both kinds: this mode exercises the
4865 incremental-build style.
4868 specifies that the CVS workspace should be maintained in a separate
4869 directory (called the 'copydir'), using checkout or update as
4870 necessary. For each build, a new workdir is created with a copy of the
4871 source tree (rm -rf workdir; cp -r copydir workdir). This doubles the
4872 disk space required, but keeps the bandwidth low (update instead of a
4873 full checkout). A full 'clean' build is performed each time. This
4874 avoids any generated-file build problems, but is still occasionally
4875 vulnerable to CVS problems such as a repository being manually
4876 rearranged, causing CVS errors on update which are not an issue with a
4879 @c TODO: something is screwy about this, revisit. Is it the source
4880 @c directory or the working directory that is deleted each time?
4883 specifes that the working directory should be deleted each time,
4884 necessitating a full checkout for each build. This insures a clean
4885 build off a complete checkout, avoiding any of the problems described
4886 above. This mode exercises the ``from-scratch'' build style.
4889 this is like @code{clobber}, except that the 'cvs export' command is
4890 used to create the working directory. This command removes all CVS
4891 metadata files (the CVS/ directories) from the tree, which is
4892 sometimes useful for creating source tarballs (to avoid including the
4893 metadata in the tar file).
4897 like all Steps, this indicates the directory where the build will take
4898 place. Source Steps are special in that they perform some operations
4899 outside of the workdir (like creating the workdir itself).
4901 @item alwaysUseLatest
4902 if True, bypass the usual ``update to the last Change'' behavior, and
4903 always update to the latest changes instead.
4906 If set, this specifies a tuple of @code{(delay, repeats)} which means
4907 that when a full VC checkout fails, it should be retried up to
4908 @var{repeats} times, waiting @var{delay} seconds between attempts. If
4909 you don't provide this, it defaults to @code{None}, which means VC
4910 operations should not be retried. This is provided to make life easier
4911 for buildslaves which are stuck behind poor network connections.
4916 My habit as a developer is to do a @code{cvs update} and @code{make} each
4917 morning. Problems can occur, either because of bad code being checked in, or
4918 by incomplete dependencies causing a partial rebuild to fail where a
4919 complete from-scratch build might succeed. A quick Builder which emulates
4920 this incremental-build behavior would use the @code{mode='update'}
4923 On the other hand, other kinds of dependency problems can cause a clean
4924 build to fail where a partial build might succeed. This frequently results
4925 from a link step that depends upon an object file that was removed from a
4926 later version of the tree: in the partial tree, the object file is still
4927 around (even though the Makefiles no longer know how to create it).
4929 ``official'' builds (traceable builds performed from a known set of
4930 source revisions) are always done as clean builds, to make sure it is
4931 not influenced by any uncontrolled factors (like leftover files from a
4932 previous build). A ``full'' Builder which behaves this way would want
4933 to use the @code{mode='clobber'} setting.
4935 Each VC system has a corresponding source checkout class: their
4936 arguments are described on the following pages.
4951 @node CVS, SVN, Source Checkout, Source Checkout
4953 @cindex CVS Checkout
4954 @bsindex buildbot.steps.source.CVS
4957 The @code{CVS} build step performs a @uref{http://www.nongnu.org/cvs/,
4958 CVS} checkout or update. It takes the following arguments:
4962 (required): specify the CVSROOT value, which points to a CVS
4963 repository, probably on a remote machine. For example, the cvsroot
4964 value you would use to get a copy of the Buildbot source code is
4965 @code{:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/buildbot}
4968 (required): specify the cvs @code{module}, which is generally a
4969 subdirectory of the CVSROOT. The cvsmodule for the Buildbot source
4970 code is @code{buildbot}.
4973 a string which will be used in a @code{-r} argument. This is most
4974 useful for specifying a branch to work on. Defaults to @code{HEAD}.
4976 @item global_options
4977 a list of flags to be put before the verb in the CVS command.
4980 if set, the number of seconds to put between the timestamp of the last
4981 known Change and the value used for the @code{-D} option. Defaults to
4982 half of the parent Build's treeStableTimer.
4987 @node SVN, Darcs, CVS, Source Checkout
4990 @cindex SVN Checkout
4991 @bsindex buildbot.steps.source.SVN
4994 The @code{SVN} build step performs a
4995 @uref{http://subversion.tigris.org, Subversion} checkout or update.
4996 There are two basic ways of setting up the checkout step, depending
4997 upon whether you are using multiple branches or not.
4999 If all of your builds use the same branch, then you should create the
5000 @code{SVN} step with the @code{svnurl} argument:
5004 (required): this specifies the @code{URL} argument that will be given
5005 to the @code{svn checkout} command. It dictates both where the
5006 repository is located and which sub-tree should be extracted. In this
5007 respect, it is like a combination of the CVS @code{cvsroot} and
5008 @code{cvsmodule} arguments. For example, if you are using a remote
5009 Subversion repository which is accessible through HTTP at a URL of
5010 @code{http://svn.example.com/repos}, and you wanted to check out the
5011 @code{trunk/calc} sub-tree, you would use
5012 @code{svnurl="http://svn.example.com/repos/trunk/calc"} as an argument
5013 to your @code{SVN} step.
5016 If, on the other hand, you are building from multiple branches, then
5017 you should create the @code{SVN} step with the @code{baseURL} and
5018 @code{defaultBranch} arguments instead:
5022 (required): this specifies the base repository URL, to which a branch
5023 name will be appended. It should probably end in a slash.
5026 this specifies the name of the branch to use when a Build does not
5027 provide one of its own. This will be appended to @code{baseURL} to
5028 create the string that will be passed to the @code{svn checkout}
5032 If you are using branches, you must also make sure your
5033 @code{ChangeSource} will report the correct branch names.
5035 @heading branch example
5037 Let's suppose that the ``MyProject'' repository uses branches for the
5038 trunk, for various users' individual development efforts, and for
5039 several new features that will require some amount of work (involving
5040 multiple developers) before they are ready to merge onto the trunk.
5041 Such a repository might be organized as follows:
5044 svn://svn.example.org/MyProject/trunk
5045 svn://svn.example.org/MyProject/branches/User1/foo
5046 svn://svn.example.org/MyProject/branches/User1/bar
5047 svn://svn.example.org/MyProject/branches/User2/baz
5048 svn://svn.example.org/MyProject/features/newthing
5049 svn://svn.example.org/MyProject/features/otherthing
5052 Further assume that we want the Buildbot to run tests against the
5053 trunk and against all the feature branches (i.e., do a
5054 checkout/compile/build of branch X when a file has been changed on
5055 branch X, when X is in the set [trunk, features/newthing,
5056 features/otherthing]). We do not want the Buildbot to automatically
5057 build any of the user branches, but it should be willing to build a
5058 user branch when explicitly requested (most likely by the user who
5061 There are three things that need to be set up to accomodate this
5062 system. The first is a ChangeSource that is capable of identifying the
5063 branch which owns any given file. This depends upon a user-supplied
5064 function, in an external program that runs in the SVN commit hook and
5065 connects to the buildmaster's @code{PBChangeSource} over a TCP
5066 connection. (you can use the ``@code{buildbot sendchange}'' utility
5067 for this purpose, but you will still need an external program to
5068 decide what value should be passed to the @code{--branch=} argument).
5069 For example, a change to a file with the SVN url of
5070 ``svn://svn.example.org/MyProject/features/newthing/src/foo.c'' should
5071 be broken down into a Change instance with
5072 @code{branch='features/newthing'} and @code{file='src/foo.c'}.
5074 The second piece is an @code{AnyBranchScheduler} which will pay
5075 attention to the desired branches. It will not pay attention to the
5076 user branches, so it will not automatically start builds in response
5077 to changes there. The AnyBranchScheduler class requires you to
5078 explicitly list all the branches you want it to use, but it would not
5079 be difficult to write a subclass which used
5080 @code{branch.startswith('features/'} to remove the need for this
5081 explicit list. Or, if you want to build user branches too, you can use
5082 AnyBranchScheduler with @code{branches=None} to indicate that you want
5083 it to pay attention to all branches.
5085 The third piece is an @code{SVN} checkout step that is configured to
5086 handle the branches correctly, with a @code{baseURL} value that
5087 matches the way the ChangeSource splits each file's URL into base,
5091 from buildbot.changes.pb import PBChangeSource
5092 from buildbot.scheduler import AnyBranchScheduler
5093 from buildbot.process import source, factory
5094 from buildbot.steps import source, shell
5096 c['change_source'] = PBChangeSource()
5097 s1 = AnyBranchScheduler('main',
5098 ['trunk', 'features/newthing', 'features/otherthing'],
5099 10*60, ['test-i386', 'test-ppc'])
5100 c['schedulers'] = [s1]
5102 f = factory.BuildFactory()
5103 f.addStep(source.SVN(mode='update',
5104 baseURL='svn://svn.example.org/MyProject/',
5105 defaultBranch='trunk'))
5106 f.addStep(shell.Compile(command="make all"))
5107 f.addStep(shell.Test(command="make test"))
5110 @{'name':'test-i386', 'slavename':'bot-i386', 'builddir':'test-i386',
5112 @{'name':'test-ppc', 'slavename':'bot-ppc', 'builddir':'test-ppc',
5117 In this example, when a change arrives with a @code{branch} attribute
5118 of ``trunk'', the resulting build will have an SVN step that
5119 concatenates ``svn://svn.example.org/MyProject/'' (the baseURL) with
5120 ``trunk'' (the branch name) to get the correct svn command. If the
5121 ``newthing'' branch has a change to ``src/foo.c'', then the SVN step
5122 will concatenate ``svn://svn.example.org/MyProject/'' with
5123 ``features/newthing'' to get the svnurl for checkout.
5125 @node Darcs, Mercurial, SVN, Source Checkout
5126 @subsubsection Darcs
5128 @cindex Darcs Checkout
5129 @bsindex buildbot.steps.source.Darcs
5132 The @code{Darcs} build step performs a
5133 @uref{http://darcs.net/, Darcs} checkout or update.
5135 Like @xref{SVN}, this step can either be configured to always check
5136 out a specific tree, or set up to pull from a particular branch that
5137 gets specified separately for each build. Also like SVN, the
5138 repository URL given to Darcs is created by concatenating a
5139 @code{baseURL} with the branch name, and if no particular branch is
5140 requested, it uses a @code{defaultBranch}. The only difference in
5141 usage is that each potential Darcs repository URL must point to a
5142 fully-fledged repository, whereas SVN URLs usually point to sub-trees
5143 of the main Subversion repository. In other words, doing an SVN
5144 checkout of @code{baseURL} is legal, but silly, since you'd probably
5145 wind up with a copy of every single branch in the whole repository.
5146 Doing a Darcs checkout of @code{baseURL} is just plain wrong, since
5147 the parent directory of a collection of Darcs repositories is not
5148 itself a valid repository.
5150 The Darcs step takes the following arguments:
5154 (required unless @code{baseURL} is provided): the URL at which the
5155 Darcs source repository is available.
5158 (required unless @code{repourl} is provided): the base repository URL,
5159 to which a branch name will be appended. It should probably end in a
5163 (allowed if and only if @code{baseURL} is provided): this specifies
5164 the name of the branch to use when a Build does not provide one of its
5165 own. This will be appended to @code{baseURL} to create the string that
5166 will be passed to the @code{darcs get} command.
5169 @node Mercurial, Arch, Darcs, Source Checkout
5170 @subsubsection Mercurial
5172 @cindex Mercurial Checkout
5173 @bsindex buildbot.steps.source.Mercurial
5176 The @code{Mercurial} build step performs a
5177 @uref{http://selenic.com/mercurial, Mercurial} (aka ``hg'') checkout
5180 Branches are handled just like @xref{Darcs}.
5182 The Mercurial step takes the following arguments:
5186 (required unless @code{baseURL} is provided): the URL at which the
5187 Mercurial source repository is available.
5190 (required unless @code{repourl} is provided): the base repository URL,
5191 to which a branch name will be appended. It should probably end in a
5195 (allowed if and only if @code{baseURL} is provided): this specifies
5196 the name of the branch to use when a Build does not provide one of its
5197 own. This will be appended to @code{baseURL} to create the string that
5198 will be passed to the @code{hg clone} command.
5202 @node Arch, Bazaar, Mercurial, Source Checkout
5205 @cindex Arch Checkout
5206 @bsindex buildbot.steps.source.Arch
5209 The @code{Arch} build step performs an @uref{http://gnuarch.org/,
5210 Arch} checkout or update using the @code{tla} client. It takes the
5211 following arguments:
5215 (required): this specifies the URL at which the Arch source archive is
5219 (required): this specifies which ``development line'' (like a branch)
5220 should be used. This provides the default branch name, but individual
5221 builds may specify a different one.
5224 (optional): Each repository knows its own archive name. If this
5225 parameter is provided, it must match the repository's archive name.
5226 The parameter is accepted for compatibility with the @code{Bazaar}
5231 @node Bazaar, Bzr, Arch, Source Checkout
5232 @subsubsection Bazaar
5234 @cindex Bazaar Checkout
5235 @bsindex buildbot.steps.source.Bazaar
5238 @code{Bazaar} is an alternate implementation of the Arch VC system,
5239 which uses a client named @code{baz}. The checkout semantics are just
5240 different enough from @code{tla} that there is a separate BuildStep for
5243 It takes exactly the same arguments as @code{Arch}, except that the
5244 @code{archive=} parameter is required. (baz does not emit the archive
5245 name when you do @code{baz register-archive}, so we must provide it
5249 @node Bzr, P4, Bazaar, Source Checkout
5252 @cindex Bzr Checkout
5253 @bsindex buildbot.steps.source.Bzr
5255 @code{bzr} is a descendant of Arch/Baz, and is frequently referred to
5256 as simply ``Bazaar''. The repository-vs-workspace model is similar to
5257 Darcs, but it uses a strictly linear sequence of revisions (one
5258 history per branch) like Arch. Branches are put in subdirectories.
5259 This makes it look very much like Mercurial, so it takes the same
5265 (required unless @code{baseURL} is provided): the URL at which the
5266 Bzr source repository is available.
5269 (required unless @code{repourl} is provided): the base repository URL,
5270 to which a branch name will be appended. It should probably end in a
5274 (allowed if and only if @code{baseURL} is provided): this specifies
5275 the name of the branch to use when a Build does not provide one of its
5276 own. This will be appended to @code{baseURL} to create the string that
5277 will be passed to the @code{bzr checkout} command.
5282 @node P4, Git, Bzr, Source Checkout
5285 @cindex Perforce Update
5286 @bsindex buildbot.steps.source.P4
5287 @c TODO @bsindex buildbot.steps.source.P4Sync
5290 The @code{P4} build step creates a @uref{http://www.perforce.com/,
5291 Perforce} client specification and performs an update.
5295 A view into the Perforce depot without branch name or trailing "...".
5296 Typically "//depot/proj/".
5298 A branch name to append on build requests if none is specified.
5301 (optional): the host:port string describing how to get to the P4 Depot
5302 (repository), used as the -p argument for all p4 commands.
5304 (optional): the Perforce user, used as the -u argument to all p4
5307 (optional): the Perforce password, used as the -p argument to all p4
5310 (optional): a list of (depotpath, clientpath) tuples containing extra
5311 views to be mapped into the client specification. Both will have
5312 "/..." appended automatically. The client name and source directory
5313 will be prepended to the client path.
5315 (optional): The name of the client to use. In mode='copy' and
5316 mode='update', it's particularly important that a unique name is used
5317 for each checkout directory to avoid incorrect synchronization. For
5318 this reason, Python percent substitution will be performed on this value
5319 to replace %(slave)s with the slave name and %(builder)s with the
5320 builder name. The default is "buildbot_%(slave)s_%(build)s".
5324 @node Git, , P4, Source Checkout
5327 @cindex Git Checkout
5328 @bsindex buildbot.steps.source.Git
5330 The @code{Git} build step clones or updates a @uref{http://git.or.cz/,
5331 Git} repository and checks out the specified branch or revision. Note
5332 that the buildbot supports Git version 1.2.0 and later: earlier
5333 versions (such as the one shipped in Ubuntu 'Dapper') do not support
5334 the @command{git init} command that the buildbot uses.
5336 The Git step takes the following arguments:
5340 (required): the URL of the upstream Git repository.
5343 (optional): this specifies the name of the branch to use when a Build
5344 does not provide one of its own. If this this parameter is not
5345 specified, and the Build does not provide a branch, the ``master''
5346 branch will be used.
5350 @node ShellCommand, Simple ShellCommand Subclasses, Source Checkout, Build Steps
5351 @subsection ShellCommand
5353 @bsindex buildbot.steps.shell.ShellCommand
5354 @c TODO @bsindex buildbot.steps.shell.TreeSize
5356 This is a useful base class for just about everything you might want
5357 to do during a build (except for the initial source checkout). It runs
5358 a single command in a child shell on the buildslave. All stdout/stderr
5359 is recorded into a LogFile. The step finishes with a status of FAILURE
5360 if the command's exit code is non-zero, otherwise it has a status of
5363 The preferred way to specify the command is with a list of argv strings,
5364 since this allows for spaces in filenames and avoids doing any fragile
5365 shell-escaping. You can also specify the command with a single string, in
5366 which case the string is given to '/bin/sh -c COMMAND' for parsing.
5368 On Windows, commands are run via @code{cmd.exe /c} which works well. However,
5369 if you're running a batch file, the error level does not get propagated
5370 correctly unless you add 'call' before your batch file's name:
5371 @code{cmd=['call', 'myfile.bat', ...]}.
5373 All ShellCommands are run by default in the ``workdir'', which
5374 defaults to the ``@file{build}'' subdirectory of the slave builder's
5375 base directory. The absolute path of the workdir will thus be the
5376 slave's basedir (set as an option to @code{buildbot create-slave},
5377 @pxref{Creating a buildslave}) plus the builder's basedir (set in the
5378 builder's @code{c['builddir']} key in master.cfg) plus the workdir
5379 itself (a class-level attribute of the BuildFactory, defaults to
5382 @code{ShellCommand} arguments:
5386 a list of strings (preferred) or single string (discouraged) which
5387 specifies the command to be run. A list of strings is preferred
5388 because it can be used directly as an argv array. Using a single
5389 string (with embedded spaces) requires the buildslave to pass the
5390 string to /bin/sh for interpretation, which raises all sorts of
5391 difficult questions about how to escape or interpret shell
5395 a dictionary of environment strings which will be added to the child
5396 command's environment. For example, to run tests with a different i18n
5397 language setting, you might use
5400 f.addStep(ShellCommand(command=["make", "test"],
5401 env=@{'LANG': 'fr_FR'@}))
5404 These variable settings will override any existing ones in the
5405 buildslave's environment or the environment specified in the
5406 Builder. The exception is PYTHONPATH, which is merged
5407 with (actually prepended to) any existing $PYTHONPATH setting. The
5408 value is treated as a list of directories to prepend, and a single
5409 string is treated like a one-item list. For example, to prepend both
5410 @file{/usr/local/lib/python2.3} and @file{/home/buildbot/lib/python}
5411 to any existing $PYTHONPATH setting, you would do something like the
5415 f.addStep(ShellCommand(
5416 command=["make", "test"],
5417 env=@{'PYTHONPATH': ["/usr/local/lib/python2.3",
5418 "/home/buildbot/lib/python"] @}))
5422 if False, stdout from the child process is discarded rather than being
5423 sent to the buildmaster for inclusion in the step's LogFile.
5426 like @code{want_stdout} but for stderr. Note that commands run through
5427 a PTY do not have separate stdout/stderr streams: both are merged into
5431 Sometimes commands will log interesting data to a local file, rather
5432 than emitting everything to stdout or stderr. For example, Twisted's
5433 ``trial'' command (which runs unit tests) only presents summary
5434 information to stdout, and puts the rest into a file named
5435 @file{_trial_temp/test.log}. It is often useful to watch these files
5436 as the command runs, rather than using @command{/bin/cat} to dump
5437 their contents afterwards.
5439 The @code{logfiles=} argument allows you to collect data from these
5440 secondary logfiles in near-real-time, as the step is running. It
5441 accepts a dictionary which maps from a local Log name (which is how
5442 the log data is presented in the build results) to a remote filename
5443 (interpreted relative to the build's working directory). Each named
5444 file will be polled on a regular basis (every couple of seconds) as
5445 the build runs, and any new text will be sent over to the buildmaster.
5448 f.addStep(ShellCommand(
5449 command=["make", "test"],
5450 logfiles=@{"triallog": "_trial_temp/test.log"@}))
5455 if the command fails to produce any output for this many seconds, it
5456 is assumed to be locked up and will be killed.
5459 This will be used to describe the command (on the Waterfall display)
5460 while the command is still running. It should be a single
5461 imperfect-tense verb, like ``compiling'' or ``testing''. The preferred
5462 form is a list of short strings, which allows the HTML Waterfall
5463 display to create narrower columns by emitting a <br> tag between each
5464 word. You may also provide a single string.
5466 @item descriptionDone
5467 This will be used to describe the command once it has finished. A
5468 simple noun like ``compile'' or ``tests'' should be used. Like
5469 @code{description}, this may either be a list of short strings or a
5472 If neither @code{description} nor @code{descriptionDone} are set, the
5473 actual command arguments will be used to construct the description.
5474 This may be a bit too wide to fit comfortably on the Waterfall
5478 f.addStep(ShellCommand(command=["make", "test"],
5479 description=["testing"],
5480 descriptionDone=["tests"]))
5484 If this option is true (the default), then the step's logfile will describe the
5485 environment variables on the slave. In situations where the environment is not
5486 relevant and is long, it may be easier to set @code{logEnviron=False}.
5490 @node Simple ShellCommand Subclasses, Python BuildSteps, ShellCommand, Build Steps
5491 @subsection Simple ShellCommand Subclasses
5493 Several subclasses of ShellCommand are provided as starting points for
5494 common build steps. These are all very simple: they just override a few
5495 parameters so you don't have to specify them yourself, making the master.cfg
5507 @node Configure, Compile, Simple ShellCommand Subclasses, Simple ShellCommand Subclasses
5508 @subsubsection Configure
5510 @bsindex buildbot.steps.shell.Configure
5512 This is intended to handle the @code{./configure} step from
5513 autoconf-style projects, or the @code{perl Makefile.PL} step from perl
5514 MakeMaker.pm-style modules. The default command is @code{./configure}
5515 but you can change this by providing a @code{command=} parameter.
5517 @node Compile, Test, Configure, Simple ShellCommand Subclasses
5518 @subsubsection Compile
5520 @bsindex buildbot.steps.shell.Compile
5522 This is meant to handle compiling or building a project written in C.
5523 The default command is @code{make all}. When the compile is finished,
5524 the log file is scanned for GCC warning messages, a summary log is
5525 created with any problems that were seen, and the step is marked as
5526 WARNINGS if any were discovered. The number of warnings is stored in a
5527 Build Property named ``warnings-count'', which is accumulated over all
5528 Compile steps (so if two warnings are found in one step, and three are
5529 found in another step, the overall build will have a
5530 ``warnings-count'' property of 5.
5532 The default regular expression used to detect a warning is
5533 @code{'.*warning[: ].*'} , which is fairly liberal and may cause
5534 false-positives. To use a different regexp, provide a
5535 @code{warningPattern=} argument, or use a subclass which sets the
5536 @code{warningPattern} attribute:
5539 f.addStep(Compile(command=["make", "test"],
5540 warningPattern="^Warning: "))
5543 The @code{warningPattern=} can also be a pre-compiled python regexp
5544 object: this makes it possible to add flags like @code{re.I} (to use
5545 case-insensitive matching).
5547 (TODO: this step needs to be extended to look for GCC error messages
5548 as well, and collect them into a separate logfile, along with the
5549 source code filenames involved).
5552 @node Test, TreeSize, Compile, Simple ShellCommand Subclasses
5555 @bsindex buildbot.steps.shell.Test
5557 This is meant to handle unit tests. The default command is @code{make
5558 test}, and the @code{warnOnFailure} flag is set.
5560 @node TreeSize, PerlModuleTest, Test, Simple ShellCommand Subclasses
5561 @subsubsection TreeSize
5563 @bsindex buildbot.steps.shell.TreeSize
5565 This is a simple command that uses the 'du' tool to measure the size
5566 of the code tree. It puts the size (as a count of 1024-byte blocks,
5567 aka 'KiB' or 'kibibytes') on the step's status text, and sets a build
5568 property named 'tree-size-KiB' with the same value.
5570 @node PerlModuleTest, SetProperty, TreeSize, Simple ShellCommand Subclasses
5571 @subsubsection PerlModuleTest
5573 @bsindex buildbot.steps.shell.PerlModuleTest
5575 This is a simple command that knows how to run tests of perl modules.
5576 It parses the output to determine the number of tests passed and
5577 failed and total number executed, saving the results for later query.
5579 @node SetProperty, , PerlModuleTest, Simple ShellCommand Subclasses
5580 @subsubsection SetProperty
5582 @bsindex buildbot.steps.shell.SetProperty
5584 This buildstep is similar to ShellCommand, except that it captures the
5585 output of the command into a property. It is usually used like this:
5588 f.addStep(SetProperty(command="uname -a", property="uname"))
5591 This runs @code{uname -a} and captures its stdout, stripped of leading
5592 and trailing whitespace, in the property "uname". To avoid stripping,
5593 add @code{strip=False}. The @code{property} argument can be specified
5594 as a @code{WithProperties} object.
5596 The more advanced usage allows you to specify a function to extract
5597 properties from the command output. Here you can use regular
5598 expressions, string interpolation, or whatever you would like.
5599 The function is called with three arguments: the exit status of the
5600 command, its standard output as a string, and its standard error as
5601 a string. It should return a dictionary containing all new properties.
5604 def glob2list(rc, stdout, stderr):
5605 jpgs = [ l.strip() for l in stdout.split('\n') ]
5606 return @{ 'jpgs' : jpgs @}
5607 f.addStep(SetProperty(command="ls -1 *.jpg", extract_fn=glob2list))
5610 Note that any ordering relationship of the contents of stdout and
5611 stderr is lost. For example, given
5614 f.addStep(SetProperty(
5615 command="echo output1; echo error >&2; echo output2",
5616 extract_fn=my_extract))
5619 Then @code{my_extract} will see @code{stdout="output1\noutput2\n"}
5620 and @code{stderr="error\n"}.
5622 @node Python BuildSteps, Transferring Files, Simple ShellCommand Subclasses, Build Steps
5623 @subsection Python BuildSteps
5625 Here are some BuildSteps that are specifcally useful for projects
5626 implemented in Python.
5635 @subsubsection BuildEPYDoc
5637 @bsindex buildbot.steps.python.BuildEPYDoc
5639 @url{http://epydoc.sourceforge.net/, epydoc} is a tool for generating
5640 API documentation for Python modules from their docstrings. It reads
5641 all the .py files from your source tree, processes the docstrings
5642 therein, and creates a large tree of .html files (or a single .pdf
5645 The @code{buildbot.steps.python.BuildEPYDoc} step will run
5646 @command{epydoc} to produce this API documentation, and will count the
5647 errors and warnings from its output.
5649 You must supply the command line to be used. The default is
5650 @command{make epydocs}, which assumes that your project has a Makefile
5651 with an ``epydocs'' target. You might wish to use something like
5652 @command{epydoc -o apiref source/PKGNAME} instead. You might also want
5653 to add @command{--pdf} to generate a PDF file instead of a large tree
5656 The API docs are generated in-place in the build tree (under the
5657 workdir, in the subdirectory controlled by the ``-o'' argument). To
5658 make them useful, you will probably have to copy them to somewhere
5659 they can be read. A command like @command{rsync -ad apiref/
5660 dev.example.com:~public_html/current-apiref/} might be useful. You
5661 might instead want to bundle them into a tarball and publish it in the
5662 same place where the generated install tarball is placed.
5665 from buildbot.steps.python import BuildEPYDoc
5668 f.addStep(BuildEPYDoc(command=["epydoc", "-o", "apiref", "source/mypkg"]))
5673 @subsubsection PyFlakes
5675 @bsindex buildbot.steps.python.PyFlakes
5677 @url{http://divmod.org/trac/wiki/DivmodPyflakes, PyFlakes} is a tool
5678 to perform basic static analysis of Python code to look for simple
5679 errors, like missing imports and references of undefined names. It is
5680 like a fast and simple form of the C ``lint'' program. Other tools
5681 (like pychecker) provide more detailed results but take longer to run.
5683 The @code{buildbot.steps.python.PyFlakes} step will run pyflakes and
5684 count the various kinds of errors and warnings it detects.
5686 You must supply the command line to be used. The default is
5687 @command{make pyflakes}, which assumes you have a top-level Makefile
5688 with a ``pyflakes'' target. You might want to use something like
5689 @command{pyflakes .} or @command{pyflakes src}.
5692 from buildbot.steps.python import PyFlakes
5695 f.addStep(PyFlakes(command=["pyflakes", "src"]))
5699 @subsubsection PyLint
5701 @bsindex buildbot.steps.python.PyLint
5703 Similarly, the @code{buildbot.steps.python.PyLint} step will run pylint and
5704 analyze the results.
5706 You must supply the command line to be used. There is no default.
5709 from buildbot.steps.python import PyLint
5712 f.addStep(PyLint(command=["pylint", "src"]))
5716 @node Transferring Files
5717 @subsection Transferring Files
5719 @cindex File Transfer
5720 @bsindex buildbot.steps.transfer.FileUpload
5721 @bsindex buildbot.steps.transfer.FileDownload
5722 @bsindex buildbot.steps.transfer.DirectoryUpload
5724 Most of the work involved in a build will take place on the
5725 buildslave. But occasionally it is useful to do some work on the
5726 buildmaster side. The most basic way to involve the buildmaster is
5727 simply to move a file from the slave to the master, or vice versa.
5728 There are a pair of BuildSteps named @code{FileUpload} and
5729 @code{FileDownload} to provide this functionality. @code{FileUpload}
5730 moves a file @emph{up to} the master, while @code{FileDownload} moves
5731 a file @emph{down from} the master.
5733 As an example, let's assume that there is a step which produces an
5734 HTML file within the source tree that contains some sort of generated
5735 project documentation. We want to move this file to the buildmaster,
5736 into a @file{~/public_html} directory, so it can be visible to
5737 developers. This file will wind up in the slave-side working directory
5738 under the name @file{docs/reference.html}. We want to put it into the
5739 master-side @file{~/public_html/ref.html}.
5742 from buildbot.steps.shell import ShellCommand
5743 from buildbot.steps.transfer import FileUpload
5745 f.addStep(ShellCommand(command=["make", "docs"]))
5746 f.addStep(FileUpload(slavesrc="docs/reference.html",
5747 masterdest="~/public_html/ref.html"))
5750 The @code{masterdest=} argument will be passed to os.path.expanduser,
5751 so things like ``~'' will be expanded properly. Non-absolute paths
5752 will be interpreted relative to the buildmaster's base directory.
5753 Likewise, the @code{slavesrc=} argument will be expanded and
5754 interpreted relative to the builder's working directory.
5757 To move a file from the master to the slave, use the
5758 @code{FileDownload} command. For example, let's assume that some step
5759 requires a configuration file that, for whatever reason, could not be
5760 recorded in the source code repository or generated on the buildslave
5764 from buildbot.steps.shell import ShellCommand
5765 from buildbot.steps.transfer import FileUpload
5767 f.addStep(FileDownload(mastersrc="~/todays_build_config.txt",
5768 slavedest="build_config.txt"))
5769 f.addStep(ShellCommand(command=["make", "config"]))
5772 Like @code{FileUpload}, the @code{mastersrc=} argument is interpreted
5773 relative to the buildmaster's base directory, and the
5774 @code{slavedest=} argument is relative to the builder's working
5775 directory. If the buildslave is running in @file{~buildslave}, and the
5776 builder's ``builddir'' is something like @file{tests-i386}, then the
5777 workdir is going to be @file{~buildslave/tests-i386/build}, and a
5778 @code{slavedest=} of @file{foo/bar.html} will get put in
5779 @file{~buildslave/tests-i386/build/foo/bar.html}. Both of these commands
5780 will create any missing intervening directories.
5782 @subheading Other Parameters
5784 The @code{maxsize=} argument lets you set a maximum size for the file
5785 to be transferred. This may help to avoid surprises: transferring a
5786 100MB coredump when you were expecting to move a 10kB status file
5787 might take an awfully long time. The @code{blocksize=} argument
5788 controls how the file is sent over the network: larger blocksizes are
5789 slightly more efficient but also consume more memory on each end, and
5790 there is a hard-coded limit of about 640kB.
5792 The @code{mode=} argument allows you to control the access permissions
5793 of the target file, traditionally expressed as an octal integer. The
5794 most common value is probably 0755, which sets the ``x'' executable
5795 bit on the file (useful for shell scripts and the like). The default
5796 value for @code{mode=} is None, which means the permission bits will
5797 default to whatever the umask of the writing process is. The default
5798 umask tends to be fairly restrictive, but at least on the buildslave
5799 you can make it less restrictive with a --umask command-line option at
5800 creation time (@pxref{Buildslave Options}).
5802 @subheading Transfering Directories
5804 To transfer complete directories from the buildslave to the master, there
5805 is a BuildStep named @code{DirectoryUpload}. It works like @code{FileUpload},
5806 just for directories. However it does not support the @code{maxsize},
5807 @code{blocksize} and @code{mode} arguments. As an example, let's assume an
5808 generated project documentation, which consists of many files (like the output
5809 of doxygen or epydoc). We want to move the entire documentation to the
5810 buildmaster, into a @code{~/public_html/docs} directory. On the slave-side
5811 the directory can be found under @code{docs}:
5814 from buildbot.steps.shell import ShellCommand
5815 from buildbot.steps.transfer import DirectoryUpload
5817 f.addStep(ShellCommand(command=["make", "docs"]))
5818 f.addStep(DirectoryUpload(slavesrc="docs",
5819 masterdest="~/public_html/docs"))
5822 The DirectoryUpload step will create all necessary directories and
5823 transfers empty directories, too.
5825 @node Steps That Run on the Master
5826 @subsection Steps That Run on the Master
5828 Occasionally, it is useful to execute some task on the master, for example to
5829 create a directory, deploy a build result, or trigger some other centralized
5830 processing. This is possible, in a limited fashion, with the
5831 @code{MasterShellCommand} step.
5833 This step operates similarly to a regular @code{ShellCommand}, but executes on
5834 the master, instead of the slave. To be clear, the enclosing @code{Build}
5835 object must still have a slave object, just as for any other step -- only, in
5836 this step, the slave does not do anything.
5838 In this example, the step renames a tarball based on the day of the week.
5841 from buildbot.steps.transfer import FileUpload
5842 from buildbot.steps.master import MasterShellCommand
5844 f.addStep(FileUpload(slavesrc="widgetsoft.tar.gz",
5845 masterdest="/var/buildoutputs/widgetsoft-new.tar.gz"))
5846 f.addStep(MasterShellCommand(command="""
5847 cd /var/buildoutputs;
5848 mv widgetsoft-new.tar.gz widgetsoft-`date +%a`.tar.gz"""))
5851 @node Triggering Schedulers
5852 @subsection Triggering Schedulers
5854 The counterpart to the Triggerable described in section
5855 @pxref{Triggerable Scheduler} is the Trigger BuildStep.
5858 from buildbot.steps.trigger import Trigger
5859 f.addStep(Trigger(schedulerNames=['build-prep'],
5861 updateSourceStamp=True))
5864 The @code{schedulerNames=} argument lists the Triggerables
5865 that should be triggered when this step is executed. Note that
5866 it is possible, but not advisable, to create a cycle where a build
5867 continually triggers itself, because the schedulers are specified
5870 If @code{waitForFinish} is True, then the step will not finish until
5871 all of the builds from the triggered schedulers have finished. If this
5872 argument is False (the default) or not given, then the buildstep
5873 succeeds immediately after triggering the schedulers.
5875 If @code{updateSourceStamp} is True (the default), then step updates
5876 the SourceStamp given to the Triggerables to include
5877 @code{got_revision} (the revision actually used in this build) as
5878 @code{revision} (the revision to use in the triggered builds). This is
5879 useful to ensure that all of the builds use exactly the same
5880 SourceStamp, even if other Changes have occurred while the build was
5883 @node Writing New BuildSteps
5884 @subsection Writing New BuildSteps
5886 While it is a good idea to keep your build process self-contained in
5887 the source code tree, sometimes it is convenient to put more
5888 intelligence into your Buildbot configuration. One way to do this is
5889 to write a custom BuildStep. Once written, this Step can be used in
5890 the @file{master.cfg} file.
5892 The best reason for writing a custom BuildStep is to better parse the
5893 results of the command being run. For example, a BuildStep that knows
5894 about JUnit could look at the logfiles to determine which tests had
5895 been run, how many passed and how many failed, and then report more
5896 detailed information than a simple @code{rc==0} -based ``good/bad''
5900 * Writing BuildStep Constructors::
5901 * BuildStep LogFiles::
5902 * Reading Logfiles::
5903 * Adding LogObservers::
5907 @node Writing BuildStep Constructors
5908 @subsubsection Writing BuildStep Constructors
5910 BuildStep classes have some extra equipment, because they are their own
5911 factories. Consider the use of a BuildStep in @file{master.cfg}:
5914 f.addStep(MyStep(someopt="stuff", anotheropt=1))
5917 This creates a single instance of class @code{MyStep}. However, Buildbot needs
5918 a new object each time the step is executed. this is accomplished by storing
5919 the information required to instantiate a new object in the @code{factory}
5920 attribute. When the time comes to construct a new Build, BuildFactory consults
5921 this attribute (via @code{getStepFactory}) and instantiates a new step object.
5923 When writing a new step class, then, keep in mind are that you cannot do
5924 anything "interesting" in the constructor -- limit yourself to checking and
5925 storing arguments. To ensure that these arguments are provided to any new
5926 objects, call @code{self.addFactoryArguments} with any keyword arguments your
5929 Keep a @code{**kwargs} argument on the end of your options, and pass that up to
5930 the parent class's constructor.
5932 The whole thing looks like this:
5935 class Frobinfy(LoggingBuildStep):
5943 if frob_how_many is None:
5944 raise TypeError("Frobinfy argument how_many is required")
5947 LoggingBuildStep.__init__(self, **kwargs)
5949 # and record arguments for later
5950 self.addFactoryArguments(
5951 frob_what=frob_what,
5952 frob_how_many=frob_how_many,
5955 class FastFrobnify(Frobnify):
5959 Frobnify.__init__(self, **kwargs)
5960 self.addFactoryArguments(
5964 @node BuildStep LogFiles
5965 @subsubsection BuildStep LogFiles
5967 Each BuildStep has a collection of ``logfiles''. Each one has a short
5968 name, like ``stdio'' or ``warnings''. Each LogFile contains an
5969 arbitrary amount of text, usually the contents of some output file
5970 generated during a build or test step, or a record of everything that
5971 was printed to stdout/stderr during the execution of some command.
5973 These LogFiles are stored to disk, so they can be retrieved later.
5975 Each can contain multiple ``channels'', generally limited to three
5976 basic ones: stdout, stderr, and ``headers''. For example, when a
5977 ShellCommand runs, it writes a few lines to the ``headers'' channel to
5978 indicate the exact argv strings being run, which directory the command
5979 is being executed in, and the contents of the current environment
5980 variables. Then, as the command runs, it adds a lot of ``stdout'' and
5981 ``stderr'' messages. When the command finishes, a final ``header''
5982 line is added with the exit code of the process.
5984 Status display plugins can format these different channels in
5985 different ways. For example, the web page shows LogFiles as text/html,
5986 with header lines in blue text, stdout in black, and stderr in red. A
5987 different URL is available which provides a text/plain format, in
5988 which stdout and stderr are collapsed together, and header lines are
5989 stripped completely. This latter option makes it easy to save the
5990 results to a file and run @command{grep} or whatever against the
5993 Each BuildStep contains a mapping (implemented in a python dictionary)
5994 from LogFile name to the actual LogFile objects. Status plugins can
5995 get a list of LogFiles to display, for example, a list of HREF links
5996 that, when clicked, provide the full contents of the LogFile.
5998 @heading Using LogFiles in custom BuildSteps
6000 The most common way for a custom BuildStep to use a LogFile is to
6001 summarize the results of a ShellCommand (after the command has
6002 finished running). For example, a compile step with thousands of lines
6003 of output might want to create a summary of just the warning messages.
6004 If you were doing this from a shell, you would use something like:
6007 grep "warning:" output.log >warnings.log
6010 In a custom BuildStep, you could instead create a ``warnings'' LogFile
6011 that contained the same text. To do this, you would add code to your
6012 @code{createSummary} method that pulls lines from the main output log
6013 and creates a new LogFile with the results:
6016 def createSummary(self, log):
6018 for line in log.readlines():
6019 if "warning:" in line:
6021 self.addCompleteLog('warnings', "".join(warnings))
6024 This example uses the @code{addCompleteLog} method, which creates a
6025 new LogFile, puts some text in it, and then ``closes'' it, meaning
6026 that no further contents will be added. This LogFile will appear in
6027 the HTML display under an HREF with the name ``warnings'', since that
6028 is the name of the LogFile.
6030 You can also use @code{addHTMLLog} to create a complete (closed)
6031 LogFile that contains HTML instead of plain text. The normal LogFile
6032 will be HTML-escaped if presented through a web page, but the HTML
6033 LogFile will not. At the moment this is only used to present a pretty
6034 HTML representation of an otherwise ugly exception traceback when
6035 something goes badly wrong during the BuildStep.
6037 In contrast, you might want to create a new LogFile at the beginning
6038 of the step, and add text to it as the command runs. You can create
6039 the LogFile and attach it to the build by calling @code{addLog}, which
6040 returns the LogFile object. You then add text to this LogFile by
6041 calling methods like @code{addStdout} and @code{addHeader}. When you
6042 are done, you must call the @code{finish} method so the LogFile can be
6043 closed. It may be useful to create and populate a LogFile like this
6044 from a LogObserver method @xref{Adding LogObservers}.
6046 The @code{logfiles=} argument to @code{ShellCommand} (see
6047 @pxref{ShellCommand}) creates new LogFiles and fills them in realtime
6048 by asking the buildslave to watch a actual file on disk. The
6049 buildslave will look for additions in the target file and report them
6050 back to the BuildStep. These additions will be added to the LogFile by
6051 calling @code{addStdout}. These secondary LogFiles can be used as the
6052 source of a LogObserver just like the normal ``stdio'' LogFile.
6054 @node Reading Logfiles
6055 @subsubsection Reading Logfiles
6057 Once a LogFile has been added to a BuildStep with @code{addLog()},
6058 @code{addCompleteLog()}, @code{addHTMLLog()}, or @code{logfiles=},
6059 your BuildStep can retrieve it by using @code{getLog()}:
6062 class MyBuildStep(ShellCommand):
6063 logfiles = @{ "nodelog": "_test/node.log" @}
6065 def evaluateCommand(self, cmd):
6066 nodelog = self.getLog("nodelog")
6067 if "STARTED" in nodelog.getText():
6073 For a complete list of the methods you can call on a LogFile, please
6074 see the docstrings on the @code{IStatusLog} class in
6075 @file{buildbot/interfaces.py}.
6078 @node Adding LogObservers, BuildStep URLs, Reading Logfiles, Writing New BuildSteps
6079 @subsubsection Adding LogObservers
6082 @cindex LogLineObserver
6084 Most shell commands emit messages to stdout or stderr as they operate,
6085 especially if you ask them nicely with a @code{--verbose} flag of some
6086 sort. They may also write text to a log file while they run. Your
6087 BuildStep can watch this output as it arrives, to keep track of how
6088 much progress the command has made. You can get a better measure of
6089 progress by counting the number of source files compiled or test cases
6090 run than by merely tracking the number of bytes that have been written
6091 to stdout. This improves the accuracy and the smoothness of the ETA
6094 To accomplish this, you will need to attach a @code{LogObserver} to
6095 one of the log channels, most commonly to the ``stdio'' channel but
6096 perhaps to another one which tracks a log file. This observer is given
6097 all text as it is emitted from the command, and has the opportunity to
6098 parse that output incrementally. Once the observer has decided that
6099 some event has occurred (like a source file being compiled), it can
6100 use the @code{setProgress} method to tell the BuildStep about the
6101 progress that this event represents.
6103 There are a number of pre-built @code{LogObserver} classes that you
6104 can choose from (defined in @code{buildbot.process.buildstep}, and of
6105 course you can subclass them to add further customization. The
6106 @code{LogLineObserver} class handles the grunt work of buffering and
6107 scanning for end-of-line delimiters, allowing your parser to operate
6108 on complete stdout/stderr lines. (Lines longer than a set maximum
6109 length are dropped; the maximum defaults to 16384 bytes, but you can
6110 change it by calling @code{setMaxLineLength()} on your
6111 @code{LogLineObserver} instance. Use @code{sys.maxint} for effective
6114 For example, let's take a look at the @code{TrialTestCaseCounter},
6115 which is used by the Trial step to count test cases as they are run.
6116 As Trial executes, it emits lines like the following:
6119 buildbot.test.test_config.ConfigTest.testDebugPassword ... [OK]
6120 buildbot.test.test_config.ConfigTest.testEmpty ... [OK]
6121 buildbot.test.test_config.ConfigTest.testIRC ... [FAIL]
6122 buildbot.test.test_config.ConfigTest.testLocks ... [OK]
6125 When the tests are finished, trial emits a long line of ``======'' and
6126 then some lines which summarize the tests that failed. We want to
6127 avoid parsing these trailing lines, because their format is less
6128 well-defined than the ``[OK]'' lines.
6130 The parser class looks like this:
6133 from buildbot.process.buildstep import LogLineObserver
6135 class TrialTestCaseCounter(LogLineObserver):
6136 _line_re = re.compile(r'^([\w\.]+) \.\.\. \[([^\]]+)\]$')
6140 def outLineReceived(self, line):
6143 if line.startswith("=" * 40):
6144 self.finished = True
6147 m = self._line_re.search(line.strip())
6149 testname, result = m.groups()
6151 self.step.setProgress('tests', self.numTests)
6154 This parser only pays attention to stdout, since that's where trial
6155 writes the progress lines. It has a mode flag named @code{finished} to
6156 ignore everything after the ``===='' marker, and a scary-looking
6157 regular expression to match each line while hopefully ignoring other
6158 messages that might get displayed as the test runs.
6160 Each time it identifies a test has been completed, it increments its
6161 counter and delivers the new progress value to the step with
6162 @code{self.step.setProgress}. This class is specifically measuring
6163 progress along the ``tests'' metric, in units of test cases (as
6164 opposed to other kinds of progress like the ``output'' metric, which
6165 measures in units of bytes). The Progress-tracking code uses each
6166 progress metric separately to come up with an overall completion
6167 percentage and an ETA value.
6169 To connect this parser into the @code{Trial} BuildStep,
6170 @code{Trial.__init__} ends with the following clause:
6173 # this counter will feed Progress along the 'test cases' metric
6174 counter = TrialTestCaseCounter()
6175 self.addLogObserver('stdio', counter)
6176 self.progressMetrics += ('tests',)
6179 This creates a TrialTestCaseCounter and tells the step that the
6180 counter wants to watch the ``stdio'' log. The observer is
6181 automatically given a reference to the step in its @code{.step}
6184 @subheading A Somewhat Whimsical Example
6186 Let's say that we've got some snazzy new unit-test framework called
6187 Framboozle. It's the hottest thing since sliced bread. It slices, it
6188 dices, it runs unit tests like there's no tomorrow. Plus if your unit
6189 tests fail, you can use its name for a Web 2.1 startup company, make
6190 millions of dollars, and hire engineers to fix the bugs for you, while
6191 you spend your afternoons lazily hang-gliding along a scenic pacific
6192 beach, blissfully unconcerned about the state of your
6193 tests.@footnote{framboozle.com is still available. Remember, I get 10%
6196 To run a Framboozle-enabled test suite, you just run the 'framboozler'
6197 command from the top of your source code tree. The 'framboozler'
6198 command emits a bunch of stuff to stdout, but the most interesting bit
6199 is that it emits the line "FNURRRGH!" every time it finishes running a
6200 test case@footnote{Framboozle gets very excited about running unit
6201 tests.}. You'd like to have a test-case counting LogObserver that
6202 watches for these lines and counts them, because counting them will
6203 help the buildbot more accurately calculate how long the build will
6204 take, and this will let you know exactly how long you can sneak out of
6205 the office for your hang-gliding lessons without anyone noticing that
6208 This will involve writing a new BuildStep (probably named
6209 "Framboozle") which inherits from ShellCommand. The BuildStep class
6210 definition itself will look something like this:
6214 from buildbot.steps.shell import ShellCommand
6215 from buildbot.process.buildstep import LogLineObserver
6217 class FNURRRGHCounter(LogLineObserver):
6219 def outLineReceived(self, line):
6220 if "FNURRRGH!" in line:
6222 self.step.setProgress('tests', self.numTests)
6224 class Framboozle(ShellCommand):
6225 command = ["framboozler"]
6227 def __init__(self, **kwargs):
6228 ShellCommand.__init__(self, **kwargs) # always upcall!
6229 counter = FNURRRGHCounter())
6230 self.addLogObserver('stdio', counter)
6231 self.progressMetrics += ('tests',)
6235 So that's the code that we want to wind up using. How do we actually
6238 You have a couple of different options.
6240 Option 1: The simplest technique is to simply put this text
6241 (everything from START to FINISH) in your master.cfg file, somewhere
6242 before the BuildFactory definition where you actually use it in a
6247 f.addStep(SVN(svnurl="stuff"))
6248 f.addStep(Framboozle())
6251 Remember that master.cfg is secretly just a python program with one
6252 job: populating the BuildmasterConfig dictionary. And python programs
6253 are allowed to define as many classes as they like. So you can define
6254 classes and use them in the same file, just as long as the class is
6255 defined before some other code tries to use it.
6257 This is easy, and it keeps the point of definition very close to the
6258 point of use, and whoever replaces you after that unfortunate
6259 hang-gliding accident will appreciate being able to easily figure out
6260 what the heck this stupid "Framboozle" step is doing anyways. The
6261 downside is that every time you reload the config file, the Framboozle
6262 class will get redefined, which means that the buildmaster will think
6263 that you've reconfigured all the Builders that use it, even though
6264 nothing changed. Bleh.
6266 Option 2: Instead, we can put this code in a separate file, and import
6267 it into the master.cfg file just like we would the normal buildsteps
6268 like ShellCommand and SVN.
6270 Create a directory named ~/lib/python, put everything from START to
6271 FINISH in ~/lib/python/framboozle.py, and run your buildmaster using:
6274 PYTHONPATH=~/lib/python buildbot start MASTERDIR
6277 or use the @file{Makefile.buildbot} to control the way
6278 @command{buildbot start} works. Or add something like this to
6279 something like your ~/.bashrc or ~/.bash_profile or ~/.cshrc:
6282 export PYTHONPATH=~/lib/python
6285 Once we've done this, our master.cfg can look like:
6288 from framboozle import Framboozle
6290 f.addStep(SVN(svnurl="stuff"))
6291 f.addStep(Framboozle())
6299 f.addStep(SVN(svnurl="stuff"))
6300 f.addStep(framboozle.Framboozle())
6303 (check out the python docs for details about how "import" and "from A
6306 What we've done here is to tell python that every time it handles an
6307 "import" statement for some named module, it should look in our
6308 ~/lib/python/ for that module before it looks anywhere else. After our
6309 directories, it will try in a bunch of standard directories too
6310 (including the one where buildbot is installed). By setting the
6311 PYTHONPATH environment variable, you can add directories to the front
6312 of this search list.
6314 Python knows that once it "import"s a file, it doesn't need to
6315 re-import it again. This means that reconfiguring the buildmaster
6316 (with "buildbot reconfig", for example) won't make it think the
6317 Framboozle class has changed every time, so the Builders that use it
6318 will not be spuriously restarted. On the other hand, you either have
6319 to start your buildmaster in a slightly weird way, or you have to
6320 modify your environment to set the PYTHONPATH variable.
6323 Option 3: Install this code into a standard python library directory
6325 Find out what your python's standard include path is by asking it:
6328 80:warner@@luther% python
6329 Python 2.4.4c0 (#2, Oct 2 2006, 00:57:46)
6330 [GCC 4.1.2 20060928 (prerelease) (Debian 4.1.1-15)] on linux2
6331 Type "help", "copyright", "credits" or "license" for more information.
6334 >>> pprint.pprint(sys.path)
6336 '/usr/lib/python24.zip',
6337 '/usr/lib/python2.4',
6338 '/usr/lib/python2.4/plat-linux2',
6339 '/usr/lib/python2.4/lib-tk',
6340 '/usr/lib/python2.4/lib-dynload',
6341 '/usr/local/lib/python2.4/site-packages',
6342 '/usr/lib/python2.4/site-packages',
6343 '/usr/lib/python2.4/site-packages/Numeric',
6344 '/var/lib/python-support/python2.4',
6345 '/usr/lib/site-python']
6348 In this case, putting the code into
6349 /usr/local/lib/python2.4/site-packages/framboozle.py would work just
6350 fine. We can use the same master.cfg "import framboozle" statement as
6351 in Option 2. By putting it in a standard include directory (instead of
6352 the decidedly non-standard ~/lib/python), we don't even have to set
6353 PYTHONPATH to anything special. The downside is that you probably have
6354 to be root to write to one of those standard include directories.
6357 Option 4: Submit the code for inclusion in the Buildbot distribution
6359 Contribute the code in an Enhancement Request on SourceForge, via
6360 http://buildbot.sf.net . Lobby, convince, coerce, bribe, badger,
6361 harass, threaten, or otherwise encourage the author to accept the
6362 patch. This lets you do something like:
6365 from buildbot.steps import framboozle
6367 f.addStep(SVN(svnurl="stuff"))
6368 f.addStep(framboozle.Framboozle())
6371 And then you don't even have to install framboozle.py anywhere on your
6372 system, since it will ship with Buildbot. You don't have to be root,
6373 you don't have to set PYTHONPATH. But you do have to make a good case
6374 for Framboozle being worth going into the main distribution, you'll
6375 probably have to provide docs and some unit test cases, you'll need to
6376 figure out what kind of beer the author likes, and then you'll have to
6377 wait until the next release. But in some environments, all this is
6378 easier than getting root on your buildmaster box, so the tradeoffs may
6379 actually be worth it.
6383 Putting the code in master.cfg (1) makes it available to that
6384 buildmaster instance. Putting it in a file in a personal library
6385 directory (2) makes it available for any buildmasters you might be
6386 running. Putting it in a file in a system-wide shared library
6387 directory (3) makes it available for any buildmasters that anyone on
6388 that system might be running. Getting it into the buildbot's upstream
6389 repository (4) makes it available for any buildmasters that anyone in
6390 the world might be running. It's all a matter of how widely you want
6391 to deploy that new class.
6395 @node BuildStep URLs, , Adding LogObservers, Writing New BuildSteps
6396 @subsubsection BuildStep URLs
6399 @cindex BuildStep URLs
6402 Each BuildStep has a collection of ``links''. Like its collection of
6403 LogFiles, each link has a name and a target URL. The web status page
6404 creates HREFs for each link in the same box as it does for LogFiles,
6405 except that the target of the link is the external URL instead of an
6406 internal link to a page that shows the contents of the LogFile.
6408 These external links can be used to point at build information hosted
6409 on other servers. For example, the test process might produce an
6410 intricate description of which tests passed and failed, or some sort
6411 of code coverage data in HTML form, or a PNG or GIF image with a graph
6412 of memory usage over time. The external link can provide an easy way
6413 for users to navigate from the buildbot's status page to these
6414 external web sites or file servers. Note that the step itself is
6415 responsible for insuring that there will be a document available at
6416 the given URL (perhaps by using @command{scp} to copy the HTML output
6417 to a @file{~/public_html/} directory on a remote web server). Calling
6418 @code{addURL} does not magically populate a web server.
6420 To set one of these links, the BuildStep should call the @code{addURL}
6421 method with the name of the link and the target URL. Multiple URLs can
6424 In this example, we assume that the @command{make test} command causes
6425 a collection of HTML files to be created and put somewhere on the
6426 coverage.example.org web server, in a filename that incorporates the
6430 class TestWithCodeCoverage(BuildStep):
6431 command = ["make", "test",
6432 WithProperties("buildnum=%s" % "buildnumber")]
6434 def createSummary(self, log):
6435 buildnumber = self.getProperty("buildnumber")
6436 url = "http://coverage.example.org/builds/%s.html" % buildnumber
6437 self.addURL("coverage", url)
6440 You might also want to extract the URL from some special message
6441 output by the build process itself:
6444 class TestWithCodeCoverage(BuildStep):
6445 command = ["make", "test",
6446 WithProperties("buildnum=%s" % "buildnumber")]
6448 def createSummary(self, log):
6449 output = StringIO(log.getText())
6450 for line in output.readlines():
6451 if line.startswith("coverage-url:"):
6452 url = line[len("coverage-url:"):].strip()
6453 self.addURL("coverage", url)
6457 Note that a build process which emits both stdout and stderr might
6458 cause this line to be split or interleaved between other lines. It
6459 might be necessary to restrict the getText() call to only stdout with
6460 something like this:
6463 output = StringIO("".join([c[1]
6464 for c in log.getChunks()
6465 if c[0] == LOG_CHANNEL_STDOUT]))
6468 Of course if the build is run under a PTY, then stdout and stderr will
6469 be merged before the buildbot ever sees them, so such interleaving
6470 will be unavoidable.
6473 @node Interlocks, Build Factories, Build Steps, Build Process
6477 @slindex buildbot.locks.MasterLock
6478 @slindex buildbot.locks.SlaveLock
6479 @slindex buildbot.locks.LockAccess
6481 Until now, we assumed that a master can run builds at any slave whenever
6482 needed or desired. Some times, you want to enforce additional constraints on
6483 builds. For reasons like limited network bandwidth, old slave machines, or a
6484 self-willed data base server, you may want to limit the number of builds (or
6485 build steps) that can access a resource.
6487 The mechanism used by Buildbot is known as the read/write lock.@footnote{See
6488 http://en.wikipedia.org/wiki/Read/write_lock_pattern for more information.} It
6489 allows either many readers or a single writer but not a combination of readers
6490 and writers. The general lock has been modified and extended for use in
6491 Buildbot. Firstly, the general lock allows an infinite number of readers. In
6492 Buildbot, we often want to put an upper limit on the number of readers, for
6493 example allowing two out of five possible builds at the same time. To do this,
6494 the lock counts the number of active readers. Secondly, the terms @emph{read
6495 mode} and @emph{write mode} are confusing in Buildbot context. They have been
6496 replaced by @emph{counting mode} (since the lock counts them) and @emph{exclusive
6497 mode}. As a result of these changes, locks in Buildbot allow a number of
6498 builds (upto some fixed number) in counting mode, or they allow one build in
6501 Often, not all slaves are equal. To allow for this situation, Buildbot allows
6502 to have a separate upper limit on the count for each slave. In this way, you
6503 can have at most 3 concurrent builds at a fast slave, 2 at a slightly older
6504 slave, and 1 at all other slaves.
6506 The final thing you can specify when you introduce a new lock is its scope.
6507 Some constraints are global -- they must be enforced over all slaves. Other
6508 constraints are local to each slave. A @emph{master lock} is used for the
6509 global constraints. You can ensure for example that at most one build (of all
6510 builds running at all slaves) accesses the data base server. With a
6511 @emph{slave lock} you can add a limit local to each slave. With such a lock,
6512 you can for example enforce an upper limit to the number of active builds at a
6515 Time for a few examples. Below a master lock is defined to protect a data base,
6516 and a slave lock is created to limit the number of builds at each slave.
6519 from buildbot import locks
6521 db_lock = locks.MasterLock("database")
6522 build_lock = locks.SlaveLock("slave_builds",
6524 maxCountForSlave = @{ 'fast': 3, 'new': 2 @})
6527 After importing locks from buildbot, @code{db_lock} is defined to be a master
6528 lock. The @code{"database"} string is used for uniquely identifying the lock.
6529 At the next line, a slave lock called @code{build_lock} is created. It is
6530 identified by the @code{"slave_builds"} string. Since the requirements of the
6531 lock are a bit more complicated, two optional arguments are also specified. The
6532 @code{maxCount} parameter sets the default limit for builds in counting mode to
6533 @code{1}. For the slave called @code{'fast'} however, we want to have at most
6534 three builds, and for the slave called @code{'new'} the upper limit is two
6535 builds running at the same time.
6537 The next step is using the locks in builds. Buildbot allows a lock to be used
6538 during an entire build (from beginning to end), or only during a single build
6539 step. In the latter case, the lock is claimed for use just before the step
6540 starts, and released again when the step ends. To prevent
6541 deadlocks,@footnote{Deadlock is the situation where two or more slaves each
6542 hold a lock in exclusive mode, and in addition want to claim the lock held by
6543 the other slave exclusively as well. Since locks allow at most one exclusive
6544 user, both slaves will wait forever.} it is not possible to claim or release
6545 locks at other times.
6547 To use locks, you should add them with a @code{locks} argument.
6548 Each use of a lock is either in counting mode (that is, possibly shared with
6549 other builds) or in exclusive mode. A build or build step proceeds only when it
6550 has acquired all locks. If a build or step needs a lot of locks, it may be
6551 starved@footnote{Starving is the situation that only a few locks are available,
6552 and they are immediately grabbed by another build. As a result, it may take a
6553 long time before all locks needed by the starved build are free at the same
6554 time.} by other builds that need fewer locks.
6556 To illustrate use of locks, a few examples.
6559 from buildbot import locks
6560 from buildbot.steps import source, shell
6561 from buildbot.process import factory
6563 db_lock = locks.MasterLock("database")
6564 build_lock = locks.SlaveLock("slave_builds",
6566 maxCountForSlave = @{ 'fast': 3, 'new': 2 @})
6568 f = factory.BuildFactory()
6569 f.addStep(source.SVN(svnurl="http://example.org/svn/Trunk"))
6570 f.addStep(shell.ShellCommand(command="make all"))
6571 f.addStep(shell.ShellCommand(command="make test",
6572 locks=[db_lock.access('exclusive')]))
6574 b1 = @{'name': 'full1', 'slavename': 'fast', 'builddir': 'f1', 'factory': f,
6575 'locks': [build_lock.access('counting')] @}
6577 b2 = @{'name': 'full2', 'slavename': 'new', 'builddir': 'f2', 'factory': f.
6578 'locks': [build_lock.access('counting')] @}
6580 b3 = @{'name': 'full3', 'slavename': 'old', 'builddir': 'f3', 'factory': f.
6581 'locks': [build_lock.access('counting')] @}
6583 b4 = @{'name': 'full4', 'slavename': 'other', 'builddir': 'f4', 'factory': f.
6584 'locks': [build_lock.access('counting')] @}
6586 c['builders'] = [b1, b2, b3, b4]
6589 Here we have four slaves @code{b1}, @code{b2}, @code{b3}, and @code{b4}. Each
6590 slave performs the same checkout, make, and test build step sequence.
6591 We want to enforce that at most one test step is executed between all slaves due
6592 to restrictions with the data base server. This is done by adding the
6593 @code{locks=} parameter with the third step. It takes a list of locks with their
6594 access mode. In this case only the @code{db_lock} is needed. The exclusive
6595 access mode is used to ensure there is at most one slave that executes the test
6598 In addition to exclusive accessing the data base, we also want slaves to stay
6599 responsive even under the load of a large number of builds being triggered.
6600 For this purpose, the slave lock called @code{build_lock} is defined. Since
6601 the restraint holds for entire builds, the lock is specified in the builder
6602 with @code{'locks': [build_lock.access('counting')]}.
6603 @node Build Factories, , Interlocks, Build Process
6604 @section Build Factories
6607 Each Builder is equipped with a ``build factory'', which is
6608 responsible for producing the actual @code{Build} objects that perform
6609 each build. This factory is created in the configuration file, and
6610 attached to a Builder through the @code{factory} element of its
6613 The standard @code{BuildFactory} object creates @code{Build} objects
6614 by default. These Builds will each execute a collection of BuildSteps
6615 in a fixed sequence. Each step can affect the results of the build,
6616 but in general there is little intelligence to tie the different steps
6617 together. You can create subclasses of @code{Build} to implement more
6618 sophisticated build processes, and then use a subclass of
6619 @code{BuildFactory} (or simply set the @code{buildClass} attribute) to
6620 create instances of your new Build subclass.
6624 * BuildStep Objects::
6626 * Process-Specific build factories::
6629 @node BuildStep Objects, BuildFactory, Build Factories, Build Factories
6630 @subsection BuildStep Objects
6632 The steps used by these builds are all subclasses of @code{BuildStep}.
6633 The standard ones provided with Buildbot are documented later,
6634 @xref{Build Steps}. You can also write your own subclasses to use in
6637 The basic behavior for a @code{BuildStep} is to:
6641 run for a while, then stop
6643 possibly invoke some RemoteCommands on the attached build slave
6645 possibly produce a set of log files
6647 finish with a status described by one of four values defined in
6648 buildbot.status.builder: SUCCESS, WARNINGS, FAILURE, SKIPPED
6650 provide a list of short strings to describe the step
6652 define a color (generally green, orange, or red) with which the
6653 step should be displayed
6657 More sophisticated steps may produce additional information and
6658 provide it to later build steps, or store it in the factory to provide
6663 * BuildFactory Attributes::
6667 @node BuildFactory, Process-Specific build factories, BuildStep Objects, Build Factories
6668 @subsection BuildFactory
6670 @bfindex buildbot.process.factory.BuildFactory
6671 @bfindex buildbot.process.factory.BasicBuildFactory
6672 @c TODO: what is BasicSVN anyway?
6673 @bfindex buildbot.process.factory.BasicSVN
6675 The default @code{BuildFactory}, provided in the
6676 @code{buildbot.process.factory} module, contains an internal list of
6677 ``BuildStep specifications'': a list of @code{(step_class, kwargs)}
6678 tuples for each. These specification tuples are constructed when the
6679 config file is read, by asking the instances passed to @code{addStep}
6680 for their subclass and arguments.
6682 When asked to create a Build, the @code{BuildFactory} puts a copy of
6683 the list of step specifications into the new Build object. When the
6684 Build is actually started, these step specifications are used to
6685 create the actual set of BuildSteps, which are then executed one at a
6686 time. This serves to give each Build an independent copy of each step.
6687 For example, a build which consists of a CVS checkout followed by a
6688 @code{make build} would be constructed as follows:
6691 from buildbot.steps import source, shell
6692 from buildbot.process import factory
6694 f = factory.BuildFactory()
6695 f.addStep(source.CVS(cvsroot=CVSROOT, cvsmodule="project", mode="update"))
6696 f.addStep(shell.Compile(command=["make", "build"]))
6699 (To support config files from buildbot-0.7.5 and earlier,
6700 @code{addStep} also accepts the @code{f.addStep(shell.Compile,
6701 command=["make","build"])} form, although its use is discouraged
6702 because then the @code{Compile} step doesn't get to validate or
6703 complain about its arguments until build time. The modern
6704 pass-by-instance approach allows this validation to occur while the
6705 config file is being loaded, where the admin has a better chance of
6708 It is also possible to pass a list of steps into the
6709 @code{BuildFactory} when it is created. Using @code{addStep} is
6710 usually simpler, but there are cases where is is more convenient to
6711 create the list of steps ahead of time.:
6714 from buildbot.steps import source, shell
6715 from buildbot.process import factory
6717 all_steps = [source.CVS(cvsroot=CVSROOT, cvsmodule="project", mode="update"),
6718 shell.Compile(command=["make", "build"]),
6720 f = factory.BuildFactory(all_steps)
6724 Each step can affect the build process in the following ways:
6728 If the step's @code{haltOnFailure} attribute is True, then a failure
6729 in the step (i.e. if it completes with a result of FAILURE) will cause
6730 the whole build to be terminated immediately: no further steps will be
6731 executed, with the exception of steps with @code{alwaysRun} set to
6732 True. @code{haltOnFailure} is useful for setup steps upon which the
6733 rest of the build depends: if the CVS checkout or @code{./configure}
6734 process fails, there is no point in trying to compile or test the
6738 If the step's @code{alwaysRun} attribute is True, then it will always
6739 be run, regardless of if previous steps have failed. This is useful
6740 for cleanup steps that should always be run to return the build
6741 directory or build slave into a good state.
6744 If the @code{flunkOnFailure} or @code{flunkOnWarnings} flag is set,
6745 then a result of FAILURE or WARNINGS will mark the build as a whole as
6746 FAILED. However, the remaining steps will still be executed. This is
6747 appropriate for things like multiple testing steps: a failure in any
6748 one of them will indicate that the build has failed, however it is
6749 still useful to run them all to completion.
6752 Similarly, if the @code{warnOnFailure} or @code{warnOnWarnings} flag
6753 is set, then a result of FAILURE or WARNINGS will mark the build as
6754 having WARNINGS, and the remaining steps will still be executed. This
6755 may be appropriate for certain kinds of optional build or test steps.
6756 For example, a failure experienced while building documentation files
6757 should be made visible with a WARNINGS result but not be serious
6758 enough to warrant marking the whole build with a FAILURE.
6762 In addition, each Step produces its own results, may create logfiles,
6763 etc. However only the flags described above have any effect on the
6766 The pre-defined BuildSteps like @code{CVS} and @code{Compile} have
6767 reasonably appropriate flags set on them already. For example, without
6768 a source tree there is no point in continuing the build, so the
6769 @code{CVS} class has the @code{haltOnFailure} flag set to True. Look
6770 in @file{buildbot/steps/*.py} to see how the other Steps are
6773 Each Step is created with an additional @code{workdir} argument that
6774 indicates where its actions should take place. This is specified as a
6775 subdirectory of the slave builder's base directory, with a default
6776 value of @code{build}. This is only implemented as a step argument (as
6777 opposed to simply being a part of the base directory) because the
6778 CVS/SVN steps need to perform their checkouts from the parent
6782 * BuildFactory Attributes::
6786 @node BuildFactory Attributes, Quick builds, BuildFactory, BuildFactory
6787 @subsubsection BuildFactory Attributes
6789 Some attributes from the BuildFactory are copied into each Build.
6791 @cindex treeStableTimer
6795 (defaults to True): if True, the buildmaster keeps track of how long
6796 each step takes, so it can provide estimates of how long future builds
6797 will take. If builds are not expected to take a consistent amount of
6798 time (such as incremental builds in which a random set of files are
6799 recompiled or tested each time), this should be set to False to
6800 inhibit progress-tracking.
6805 @node Quick builds, , BuildFactory Attributes, BuildFactory
6806 @subsubsection Quick builds
6808 @bfindex buildbot.process.factory.QuickBuildFactory
6810 The difference between a ``full build'' and a ``quick build'' is that
6811 quick builds are generally done incrementally, starting with the tree
6812 where the previous build was performed. That simply means that the
6813 source-checkout step should be given a @code{mode='update'} flag, to
6814 do the source update in-place.
6816 In addition to that, the @code{useProgress} flag should be set to
6817 False. Incremental builds will (or at least the ought to) compile as
6818 few files as necessary, so they will take an unpredictable amount of
6819 time to run. Therefore it would be misleading to claim to predict how
6820 long the build will take.
6823 @node Process-Specific build factories, , BuildFactory, Build Factories
6824 @subsection Process-Specific build factories
6826 Many projects use one of a few popular build frameworks to simplify
6827 the creation and maintenance of Makefiles or other compilation
6828 structures. Buildbot provides several pre-configured BuildFactory
6829 subclasses which let you build these projects with a minimum of fuss.
6834 * Python distutils::
6835 * Python/Twisted/trial projects::
6838 @node GNUAutoconf, CPAN, Process-Specific build factories, Process-Specific build factories
6839 @subsubsection GNUAutoconf
6841 @bfindex buildbot.process.factory.GNUAutoconf
6843 @uref{http://www.gnu.org/software/autoconf/, GNU Autoconf} is a
6844 software portability tool, intended to make it possible to write
6845 programs in C (and other languages) which will run on a variety of
6846 UNIX-like systems. Most GNU software is built using autoconf. It is
6847 frequently used in combination with GNU automake. These tools both
6848 encourage a build process which usually looks like this:
6851 % CONFIG_ENV=foo ./configure --with-flags
6857 (except of course the Buildbot always skips the @code{make install}
6860 The Buildbot's @code{buildbot.process.factory.GNUAutoconf} factory is
6861 designed to build projects which use GNU autoconf and/or automake. The
6862 configuration environment variables, the configure flags, and command
6863 lines used for the compile and test are all configurable, in general
6864 the default values will be suitable.
6869 # use the s() convenience function defined earlier
6870 f = factory.GNUAutoconf(source=s(step.SVN, svnurl=URL, mode="copy"),
6871 flags=["--disable-nls"])
6878 This argument must be a step specification tuple that provides a
6879 BuildStep to generate the source tree.
6886 The command used to configure the tree. Defaults to
6887 @code{./configure}. Accepts either a string or a list of shell argv
6891 The environment used for the initial configuration step. This accepts
6892 a dictionary which will be merged into the buildslave's normal
6893 environment. This is commonly used to provide things like
6894 @code{CFLAGS="-O2 -g"} (to turn off debug symbols during the compile).
6895 Defaults to an empty dictionary.
6897 @item configureFlags
6898 A list of flags to be appended to the argument list of the configure
6899 command. This is commonly used to enable or disable specific features
6900 of the autoconf-controlled package, like @code{["--without-x"]} to
6901 disable windowing support. Defaults to an empty list.
6904 this is a shell command or list of argv values which is used to
6905 actually compile the tree. It defaults to @code{make all}. If set to
6906 None, the compile step is skipped.
6909 this is a shell command or list of argv values which is used to run
6910 the tree's self-tests. It defaults to @code{make check}. If set to
6911 None, the test step is skipped.
6916 @node CPAN, Python distutils, GNUAutoconf, Process-Specific build factories
6919 @bfindex buildbot.process.factory.CPAN
6921 Most Perl modules available from the @uref{http://www.cpan.org/, CPAN}
6922 archive use the @code{MakeMaker} module to provide configuration,
6923 build, and test services. The standard build routine for these modules
6933 (except again Buildbot skips the install step)
6935 Buildbot provides a @code{CPAN} factory to compile and test these
6942 (required): A step specification tuple, like that used by GNUAutoconf.
6945 A string which specifies the @code{perl} executable to use. Defaults
6946 to just @code{perl}.
6951 @node Python distutils, Python/Twisted/trial projects, CPAN, Process-Specific build factories
6952 @subsubsection Python distutils
6954 @bfindex buildbot.process.factory.Distutils
6956 Most Python modules use the @code{distutils} package to provide
6957 configuration and build services. The standard build process looks
6961 % python ./setup.py build
6962 % python ./setup.py install
6965 Unfortunately, although Python provides a standard unit-test framework
6966 named @code{unittest}, to the best of my knowledge @code{distutils}
6967 does not provide a standardized target to run such unit tests. (Please
6968 let me know if I'm wrong, and I will update this factory.)
6970 The @code{Distutils} factory provides support for running the build
6971 part of this process. It accepts the same @code{source=} parameter as
6972 the other build factories.
6978 (required): A step specification tuple, like that used by GNUAutoconf.
6981 A string which specifies the @code{python} executable to use. Defaults
6982 to just @code{python}.
6985 Provides a shell command which runs unit tests. This accepts either a
6986 string or a list. The default value is None, which disables the test
6987 step (since there is no common default command to run unit tests in
6993 @node Python/Twisted/trial projects, , Python distutils, Process-Specific build factories
6994 @subsubsection Python/Twisted/trial projects
6996 @bfindex buildbot.process.factory.Trial
6997 @c TODO: document these steps better
6998 @bsindex buildbot.steps.python_twisted.HLint
6999 @bsindex buildbot.steps.python_twisted.Trial
7000 @bsindex buildbot.steps.python_twisted.ProcessDocs
7001 @bsindex buildbot.steps.python_twisted.BuildDebs
7002 @bsindex buildbot.steps.python_twisted.RemovePYCs
7004 Twisted provides a unit test tool named @code{trial} which provides a
7005 few improvements over Python's built-in @code{unittest} module. Many
7006 python projects which use Twisted for their networking or application
7007 services also use trial for their unit tests. These modules are
7008 usually built and tested with something like the following:
7011 % python ./setup.py build
7012 % PYTHONPATH=build/lib.linux-i686-2.3 trial -v PROJECTNAME.test
7013 % python ./setup.py install
7016 Unfortunately, the @file{build/lib} directory into which the
7017 built/copied .py files are placed is actually architecture-dependent,
7018 and I do not yet know of a simple way to calculate its value. For many
7019 projects it is sufficient to import their libraries ``in place'' from
7020 the tree's base directory (@code{PYTHONPATH=.}).
7022 In addition, the @var{PROJECTNAME} value where the test files are
7023 located is project-dependent: it is usually just the project's
7024 top-level library directory, as common practice suggests the unit test
7025 files are put in the @code{test} sub-module. This value cannot be
7026 guessed, the @code{Trial} class must be told where to find the test
7029 The @code{Trial} class provides support for building and testing
7030 projects which use distutils and trial. If the test module name is
7031 specified, trial will be invoked. The library path used for testing
7034 One advantage of trial is that the Buildbot happens to know how to
7035 parse trial output, letting it identify which tests passed and which
7036 ones failed. The Buildbot can then provide fine-grained reports about
7037 how many tests have failed, when individual tests fail when they had
7038 been passing previously, etc.
7040 Another feature of trial is that you can give it a series of source
7041 .py files, and it will search them for special @code{test-case-name}
7042 tags that indicate which test cases provide coverage for that file.
7043 Trial can then run just the appropriate tests. This is useful for
7044 quick builds, where you want to only run the test cases that cover the
7045 changed functionality.
7050 (required): A step specification tuple, like that used by GNUAutoconf.
7053 A list (argv array) of strings which specifies the @code{python}
7054 executable to use when building the package. Defaults to just
7055 @code{['python']}. It may be useful to add flags here, to supress
7056 warnings during compilation of extension modules. This list is
7057 extended with @code{['./setup.py', 'build']} and then executed in a
7061 Provides a directory to add to @code{PYTHONPATH} when running the unit
7062 tests, if tests are being run. Defaults to @code{.} to include the
7063 project files in-place. The generated build library is frequently
7064 architecture-dependent, but may simply be @file{build/lib} for
7065 pure-python modules.
7068 Another list of strings used to build the command that actually runs
7069 trial. This is prepended to the contents of the @code{trial} argument
7070 below. It may be useful to add @code{-W} flags here to supress
7071 warnings that occur while tests are being run. Defaults to an empty
7072 list, meaning @code{trial} will be run without an explicit
7073 interpreter, which is generally what you want if you're using
7074 @file{/usr/bin/trial} instead of, say, the @file{./bin/trial} that
7075 lives in the Twisted source tree.
7078 provides the name of the @code{trial} command. It is occasionally
7079 useful to use an alternate executable, such as @code{trial2.2} which
7080 might run the tests under an older version of Python. Defaults to
7084 Provides a module name or names which contain the unit tests for this
7085 project. Accepts a string, typically @code{PROJECTNAME.test}, or a
7086 list of strings. Defaults to None, indicating that no tests should be
7087 run. You must either set this or @code{useTestCaseNames} to do anyting
7088 useful with the Trial factory.
7090 @item useTestCaseNames
7091 Tells the Step to provide the names of all changed .py files to trial,
7092 so it can look for test-case-name tags and run just the matching test
7093 cases. Suitable for use in quick builds. Defaults to False.
7096 If @code{True}, tells Trial (with the @code{--random=0} argument) to
7097 run the test cases in random order, which sometimes catches subtle
7098 inter-test dependency bugs. Defaults to @code{False}.
7101 If @code{True}, tells Trial (with the @code{--recurse} argument) to
7102 look in all subdirectories for additional test cases. It isn't clear
7103 to me how this works, but it may be useful to deal with the
7104 unknown-PROJECTNAME problem described above, and is currently used in
7105 the Twisted buildbot to accomodate the fact that test cases are now
7106 distributed through multiple twisted.SUBPROJECT.test directories.
7110 Unless one of @code{trialModule} or @code{useTestCaseNames}
7111 are set, no tests will be run.
7113 Some quick examples follow. Most of these examples assume that the
7114 target python code (the ``code under test'') can be reached directly
7115 from the root of the target tree, rather than being in a @file{lib/}
7119 # Trial(source, tests="toplevel.test") does:
7120 # python ./setup.py build
7121 # PYTHONPATH=. trial -to toplevel.test
7123 # Trial(source, tests=["toplevel.test", "other.test"]) does:
7124 # python ./setup.py build
7125 # PYTHONPATH=. trial -to toplevel.test other.test
7127 # Trial(source, useTestCaseNames=True) does:
7128 # python ./setup.py build
7129 # PYTHONPATH=. trial -to --testmodule=foo/bar.py.. (from Changes)
7131 # Trial(source, buildpython=["python2.3", "-Wall"], tests="foo.tests"):
7132 # python2.3 -Wall ./setup.py build
7133 # PYTHONPATH=. trial -to foo.tests
7135 # Trial(source, trialpython="python2.3", trial="/usr/bin/trial",
7136 # tests="foo.tests") does:
7137 # python2.3 -Wall ./setup.py build
7138 # PYTHONPATH=. python2.3 /usr/bin/trial -to foo.tests
7140 # For running trial out of the tree being tested (only useful when the
7141 # tree being built is Twisted itself):
7142 # Trial(source, trialpython=["python2.3", "-Wall"], trial="./bin/trial",
7143 # tests="foo.tests") does:
7144 # python2.3 -Wall ./setup.py build
7145 # PYTHONPATH=. python2.3 -Wall ./bin/trial -to foo.tests
7148 If the output directory of @code{./setup.py build} is known, you can
7149 pull the python code from the built location instead of the source
7150 directories. This should be able to handle variations in where the
7151 source comes from, as well as accomodating binary extension modules:
7154 # Trial(source,tests="toplevel.test",testpath='build/lib.linux-i686-2.3')
7156 # python ./setup.py build
7157 # PYTHONPATH=build/lib.linux-i686-2.3 trial -to toplevel.test
7161 @node Status Delivery, Command-line tool, Build Process, Top
7162 @chapter Status Delivery
7164 More details are available in the docstrings for each class, use a
7165 command like @code{pydoc buildbot.status.html.WebStatus} to see them.
7166 Most status delivery objects take a @code{categories=} argument, which
7167 can contain a list of ``category'' names: in this case, it will only
7168 show status for Builders that are in one of the named categories.
7170 (implementor's note: each of these objects should be a
7171 service.MultiService which will be attached to the BuildMaster object
7172 when the configuration is processed. They should use
7173 @code{self.parent.getStatus()} to get access to the top-level IStatus
7174 object, either inside @code{startService} or later. They may call
7175 @code{status.subscribe()} in @code{startService} to receive
7176 notifications of builder events, in which case they must define
7177 @code{builderAdded} and related methods. See the docstrings in
7178 @file{buildbot/interfaces.py} for full details.)
7185 * Writing New Status Plugins::
7188 @c @node Email Delivery, , Status Delivery, Status Delivery
7189 @c @subsection Email Delivery
7194 @node WebStatus, MailNotifier, Status Delivery, Status Delivery
7198 @stindex buildbot.status.web.baseweb.WebStatus
7200 The @code{buildbot.status.html.WebStatus} status target runs a small
7201 web server inside the buildmaster. You can point a browser at this web
7202 server and retrieve information about every build the buildbot knows
7203 about, as well as find out what the buildbot is currently working on.
7205 The first page you will see is the ``Welcome Page'', which contains
7206 links to all the other useful pages. This page is simply served from
7207 the @file{public_html/index.html} file in the buildmaster's base
7208 directory, where it is created by the @command{buildbot create-master}
7209 command along with the rest of the buildmaster.
7211 The most complex resource provided by @code{WebStatus} is the
7212 ``Waterfall Display'', which shows a time-based chart of events. This
7213 somewhat-busy display provides detailed information about all steps of
7214 all recent builds, and provides hyperlinks to look at individual build
7215 logs and source changes. By simply reloading this page on a regular
7216 basis, you will see a complete description of everything the buildbot
7217 is currently working on.
7219 There are also pages with more specialized information. For example,
7220 there is a page which shows the last 20 builds performed by the
7221 buildbot, one line each. Each line is a link to detailed information
7222 about that build. By adding query arguments to the URL used to reach
7223 this page, you can narrow the display to builds that involved certain
7224 branches, or which ran on certain Builders. These pages are described
7225 in great detail below.
7228 When the buildmaster is created, a subdirectory named
7229 @file{public_html/} is created in its base directory. By default, @code{WebStatus}
7230 will serve files from this directory: for example, when a user points
7231 their browser at the buildbot's @code{WebStatus} URL, they will see
7232 the contents of the @file{public_html/index.html} file. Likewise,
7233 @file{public_html/robots.txt}, @file{public_html/buildbot.css}, and
7234 @file{public_html/favicon.ico} are all useful things to have in there.
7235 The first time a buildmaster is created, the @file{public_html}
7236 directory is populated with some sample files, which you will probably
7237 want to customize for your own project. These files are all static:
7238 the buildbot does not modify them in any way as it serves them to HTTP
7242 from buildbot.status.html import WebStatus
7243 c['status'].append(WebStatus(8080))
7246 Note that the initial robots.txt file has Disallow lines for all of
7247 the dynamically-generated buildbot pages, to discourage web spiders
7248 and search engines from consuming a lot of CPU time as they crawl
7249 through the entire history of your buildbot. If you are running the
7250 buildbot behind a reverse proxy, you'll probably need to put the
7251 robots.txt file somewhere else (at the top level of the parent web
7252 server), and replace the URL prefixes in it with more suitable values.
7254 If you would like to use an alternative root directory, add the
7255 @code{public_html=..} option to the @code{WebStatus} creation:
7258 c['status'].append(WebStatus(8080, public_html="/var/www/buildbot"))
7261 In addition, if you are familiar with twisted.web @emph{Resource
7262 Trees}, you can write code to add additional pages at places inside
7263 this web space. Just use @code{webstatus.putChild} to place these
7266 The following section describes the special URLs and the status views
7271 * WebStatus Configuration Parameters::
7272 * Buildbot Web Resources::
7277 @node WebStatus Configuration Parameters, Buildbot Web Resources, WebStatus, WebStatus
7278 @subsection WebStatus Configuration Parameters
7280 The most common way to run a @code{WebStatus} is on a regular TCP
7281 port. To do this, just pass in the TCP port number when you create the
7282 @code{WebStatus} instance; this is called the @code{http_port} argument:
7285 from buildbot.status.html import WebStatus
7286 c['status'].append(WebStatus(8080))
7289 The @code{http_port} argument is actually a ``strports specification''
7290 for the port that the web server should listen on. This can be a
7291 simple port number, or a string like
7292 @code{tcp:8080:interface=127.0.0.1} (to limit connections to the
7293 loopback interface, and therefore to clients running on the same
7294 host)@footnote{It may even be possible to provide SSL access by using
7295 a specification like
7296 @code{"ssl:12345:privateKey=mykey.pen:certKey=cert.pem"}, but this is
7297 completely untested}.
7299 If instead (or in addition) you provide the @code{distrib_port}
7300 argument, a twisted.web distributed server will be started either on a
7301 TCP port (if @code{distrib_port} is like @code{"tcp:12345"}) or more
7302 likely on a UNIX socket (if @code{distrib_port} is like
7303 @code{"unix:/path/to/socket"}).
7305 The @code{distrib_port} option means that, on a host with a
7306 suitably-configured twisted-web server, you do not need to consume a
7307 separate TCP port for the buildmaster's status web page. When the web
7308 server is constructed with @code{mktap web --user}, URLs that point to
7309 @code{http://host/~username/} are dispatched to a sub-server that is
7310 listening on a UNIX socket at @code{~username/.twisted-web-pb}. On
7311 such a system, it is convenient to create a dedicated @code{buildbot}
7312 user, then set @code{distrib_port} to
7313 @code{"unix:"+os.path.expanduser("~/.twistd-web-pb")}. This
7314 configuration will make the HTML status page available at
7315 @code{http://host/~buildbot/} . Suitable URL remapping can make it
7316 appear at @code{http://host/buildbot/}, and the right virtual host
7317 setup can even place it at @code{http://buildbot.host/} .
7319 The other @code{WebStatus} argument is @code{allowForce}. If set to
7320 True, then the web page will provide a ``Force Build'' button that
7321 allows visitors to manually trigger builds. This is useful for
7322 developers to re-run builds that have failed because of intermittent
7323 problems in the test suite, or because of libraries that were not
7324 installed at the time of the previous build. You may not wish to allow
7325 strangers to cause a build to run: in that case, set this to False to
7326 remove these buttons. The default value is False.
7330 @node Buildbot Web Resources, XMLRPC server, WebStatus Configuration Parameters, WebStatus
7331 @subsection Buildbot Web Resources
7333 Certain URLs are ``magic'', and the pages they serve are created by
7334 code in various classes in the @file{buildbot.status.web} package
7335 instead of being read from disk. The most common way to access these
7336 pages is for the buildmaster admin to write or modify the
7337 @file{index.html} page to contain links to them. Of course other
7338 project web pages can contain links to these buildbot pages as well.
7340 Many pages can be modified by adding query arguments to the URL. For
7341 example, a page which shows the results of the most recent build
7342 normally does this for all builders at once. But by appending
7343 ``?builder=i386'' to the end of the URL, the page will show only the
7344 results for the ``i386'' builder. When used in this way, you can add
7345 multiple ``builder='' arguments to see multiple builders. Remembering
7346 that URL query arguments are separated @emph{from each other} with
7347 ampersands, a URL that ends in ``?builder=i386&builder=ppc'' would
7348 show builds for just those two Builders.
7350 The @code{branch=} query argument can be used on some pages. This
7351 filters the information displayed by that page down to only the builds
7352 or changes which involved the given branch. Use @code{branch=trunk} to
7353 reference the trunk: if you aren't intentionally using branches,
7354 you're probably using trunk. Multiple @code{branch=} arguments can be
7355 used to examine multiple branches at once (so appending
7356 @code{?branch=foo&branch=bar} to the URL will show builds involving
7357 either branch). No @code{branch=} arguments means to show builds and
7358 changes for all branches.
7360 Some pages may include the Builder name or the build number in the
7361 main part of the URL itself. For example, a page that describes Build
7362 #7 of the ``i386'' builder would live at @file{/builders/i386/builds/7}.
7364 The table below lists all of the internal pages and the URLs that can
7365 be used to access them.
7367 NOTE: of the pages described here, @code{/slave_status_timeline} and
7368 @code{/last_build} have not yet been implemented, and @code{/xmlrpc}
7369 has only a few methods so far. Future releases will improve this.
7375 This provides a chronologically-oriented display of the activity of
7376 all builders. It is the same display used by the Waterfall display.
7378 By adding one or more ``builder='' query arguments, the Waterfall is
7379 restricted to only showing information about the given Builders. By
7380 adding one or more ``branch='' query arguments, the display is
7381 restricted to showing information about the given branches. In
7382 addition, adding one or more ``category='' query arguments to the URL
7383 will limit the display to Builders that were defined with one of the
7386 A 'show_events=true' query argument causes the display to include
7387 non-Build events, like slaves attaching and detaching, as well as
7388 reconfiguration events. 'show_events=false' hides these events. The
7389 default is to show them.
7391 The @code{last_time=}, @code{first_time=}, and @code{show_time=}
7392 arguments will control what interval of time is displayed. The default
7393 is to show the latest events, but these can be used to look at earlier
7394 periods in history. The @code{num_events=} argument also provides a
7395 limit on the size of the displayed page.
7397 The Waterfall has references to resources many of the other portions
7398 of the URL space: @file{/builders} for access to individual builds,
7399 @file{/changes} for access to information about source code changes,
7404 This provides a rss feed summarizing all failed builds. The same
7405 query-arguments used by 'waterfall' can be added to filter the
7410 This provides an atom feed summarizing all failed builds. The same
7411 query-arguments used by 'waterfall' can be added to filter the feed
7414 @item /builders/$BUILDERNAME
7416 This describes the given Builder, and provides buttons to force a build.
7418 @item /builders/$BUILDERNAME/builds/$BUILDNUM
7420 This describes a specific Build.
7422 @item /builders/$BUILDERNAME/builds/$BUILDNUM/steps/$STEPNAME
7424 This describes a specific BuildStep.
7426 @item /builders/$BUILDERNAME/builds/$BUILDNUM/steps/$STEPNAME/logs/$LOGNAME
7428 This provides an HTML representation of a specific logfile.
7430 @item /builders/$BUILDERNAME/builds/$BUILDNUM/steps/$STEPNAME/logs/$LOGNAME/text
7432 This returns the logfile as plain text, without any HTML coloring
7433 markup. It also removes the ``headers'', which are the lines that
7434 describe what command was run and what the environment variable
7435 settings were like. This maybe be useful for saving to disk and
7436 feeding to tools like 'grep'.
7440 This provides a brief description of the ChangeSource in use
7441 (@pxref{Change Sources}).
7445 This shows detailed information about the numbered Change: who was the
7446 author, what files were changed, what revision number was represented,
7451 This summarizes each BuildSlave, including which Builders are
7452 configured to use it, whether the buildslave is currently connected or
7453 not, and host information retrieved from the buildslave itself.
7455 @item /one_line_per_build
7457 This page shows one line of text for each build, merging information
7458 from all Builders@footnote{Apparently this is the same way
7459 http://buildd.debian.org displays build status}. Each line specifies
7460 the name of the Builder, the number of the Build, what revision it
7461 used, and a summary of the results. Successful builds are in green,
7462 while failing builds are in red. The date and time of the build are
7463 added to the right-hand edge of the line. The lines are ordered by
7464 build finish timestamp.
7466 One or more @code{builder=} or @code{branch=} arguments can be used to
7467 restrict the list. In addition, a @code{numbuilds=} argument will
7468 control how many lines are displayed (20 by default).
7470 @item /one_box_per_builder
7472 This page shows a small table, with one box for each Builder,
7473 containing the results of the most recent Build. It does not show the
7474 individual steps, or the current status. This is a simple summary of
7475 buildbot status: if this page is green, then all tests are passing.
7477 As with @code{/one_line_per_build}, this page will also honor
7478 @code{builder=} and @code{branch=} arguments.
7482 This page gives a brief summary of the Buildbot itself: software
7483 version, versions of some libraries that the Buildbot depends upon,
7484 etc. It also contains a link to the buildbot.net home page.
7486 @item /slave_status_timeline
7488 (note: this page has not yet been implemented)
7490 This provides a chronological display of configuration and operational
7491 events: master startup/shutdown, slave connect/disconnect, and
7492 config-file changes. When a config-file reload is abandoned because of
7493 an error in the config file, the error is displayed on this page.
7495 This page does not show any builds.
7497 @item /last_build/$BUILDERNAME/status.png
7499 This returns a PNG image that describes the results of the most recent
7500 build, which can be referenced in an IMG tag by other pages, perhaps
7501 from a completely different site. Use it as you would a webcounter.
7505 There are also a set of web-status resources that are intended for use
7506 by other programs, rather than humans.
7512 This runs an XML-RPC server which can be used to query status
7513 information about various builds. See @ref{XMLRPC server} for more
7518 @node XMLRPC server, HTML Waterfall, Buildbot Web Resources, WebStatus
7519 @subsection XMLRPC server
7521 When using WebStatus, the buildbot runs an XML-RPC server at
7522 @file{/xmlrpc} that can be used by other programs to query build
7523 status. The following table lists the methods that can be invoked
7524 using this interface.
7527 @item getAllBuildsInInterval(start, stop)
7529 Return a list of builds that have completed after the 'start'
7530 timestamp and before the 'stop' timestamp. This looks at all Builders.
7532 The timestamps are integers, interpreted as standard unix timestamps
7533 (seconds since epoch).
7535 Each Build is returned as a tuple in the form: @code{(buildername,
7536 buildnumber, build_end, branchname, revision, results, text)}
7538 The buildnumber is an integer. 'build_end' is an integer (seconds
7539 since epoch) specifying when the build finished.
7541 The branchname is a string, which may be an empty string to indicate
7542 None (i.e. the default branch). The revision is a string whose meaning
7543 is specific to the VC system in use, and comes from the 'got_revision'
7544 build property. The results are expressed as a string, one of
7545 ('success', 'warnings', 'failure', 'exception'). The text is a list of
7546 short strings that ought to be joined by spaces and include slightly
7547 more data about the results of the build.
7549 @item getBuild(builder_name, build_number)
7551 Return information about a specific build.
7553 This returns a dictionary (aka ``struct'' in XMLRPC terms) with
7554 complete information about the build. It does not include the contents
7555 of the log files, but it has just about everything else.
7559 @node HTML Waterfall, , XMLRPC server, WebStatus
7560 @subsection HTML Waterfall
7563 @stindex buildbot.status.html.Waterfall
7565 The @code{Waterfall} status target, deprecated as of 0.7.6, is a
7566 subset of the regular @code{WebStatus} resource (@pxref{WebStatus}).
7567 This section (and the @code{Waterfall} class itself) will be removed
7568 from a future release.
7571 from buildbot.status import html
7572 w = html.WebStatus(http_port=8080)
7573 c['status'].append(w)
7578 @node MailNotifier, IRC Bot, WebStatus, Status Delivery
7579 @section MailNotifier
7583 @stindex buildbot.status.mail.MailNotifier
7585 The buildbot can also send email when builds finish. The most common
7586 use of this is to tell developers when their change has caused the
7587 build to fail. It is also quite common to send a message to a mailing
7588 list (usually named ``builds'' or similar) about every build.
7590 The @code{MailNotifier} status target is used to accomplish this. You
7591 configure it by specifying who mail should be sent to, under what
7592 circumstances mail should be sent, and how to deliver the mail. It can
7593 be configured to only send out mail for certain builders, and only
7594 send messages when the build fails, or when the builder transitions
7595 from success to failure. It can also be configured to include various
7596 build logs in each message.
7599 By default, the message will be sent to the Interested Users list
7600 (@pxref{Doing Things With Users}), which includes all developers who
7601 made changes in the build. You can add additional recipients with the
7602 extraRecipients argument.
7604 Each MailNotifier sends mail to a single set of recipients. To send
7605 different kinds of mail to different recipients, use multiple
7608 The following simple example will send an email upon the completion of
7609 each build, to just those developers whose Changes were included in
7610 the build. The email contains a description of the Build, its results,
7611 and URLs where more information can be obtained.
7614 from buildbot.status.mail import MailNotifier
7615 mn = MailNotifier(fromaddr="buildbot@@example.org", lookup="example.org")
7616 c['status'].append(mn)
7619 To get a simple one-message-per-build (say, for a mailing list), use
7620 the following form instead. This form does not send mail to individual
7621 developers (and thus does not need the @code{lookup=} argument,
7622 explained below), instead it only ever sends mail to the ``extra
7623 recipients'' named in the arguments:
7626 mn = MailNotifier(fromaddr="buildbot@@example.org",
7627 sendToInterestedUsers=False,
7628 extraRecipients=['listaddr@@example.org'])
7631 In some cases it is desirable to have different information then what
7632 is provided in a standard MailNotifier message. For this purpose
7633 MailNotifier provides the argument customMesg (a function) which allows
7634 for the creation of messages with unique content.
7636 For example it can be useful to display the last few lines of a log file
7637 and recent changes when a builder fails:
7643 text.append("STATUS: %s" % attrs['result'].title())
7645 text.extend([c.asText() for c in attrs['changes']])
7647 name, url, lines = attrs['logs'][-1]
7648 text.append("Last %d lines of '%s':" % (logLines, name))
7649 text.extend(["\t%s\n" % line for line in lines[len(lines)-logLines:]])
7651 text.append("-buildbot")
7652 return ("\n".join(text), 'plain')
7654 mn = MailNotifier(fromaddr="buildbot@@example.org",
7655 sendToInterestedUsers=False,
7657 extraRecipients=['listaddr@@example.org'],
7661 A customMesg function takes a single dict argument (see below) and returns a
7662 tuple of strings. The first string is the complete text of the message and the
7663 second is the message type ('plain' or 'html'). The 'html' type should be used
7664 when generating an HTML message:
7670 text.append('<h4>Build status %s.</h4>' % (attrs['result'].title()))
7671 if attrs['changes']:
7672 text.append('<h4>Recent Changes:</h4>')
7673 text.extend([c.asHTML() for c in attrs['changes']])
7674 name, url, lines = attrs['logs'][-1]
7675 text.append('<h4>Last %d lines of "%s":</h4>' % (logLines, name))
7677 text.append('<br>'.join([line for line in lines[len(lines)-logLines:]]))
7679 text.append('<br><br>')
7680 text.append('Full log at: %s' % url)
7681 text.append('<br><br>')
7682 text.append('<b>-buildbot</b>')
7683 return ('\n'.join(text), 'html')
7686 @heading MailNotifier arguments
7690 The email address to be used in the 'From' header.
7692 @item sendToInterestedUsers
7693 (boolean). If True (the default), send mail to all of the Interested
7694 Users. If False, only send mail to the extraRecipients list.
7696 @item extraRecipients
7697 (tuple of strings). A list of email addresses to which messages should
7698 be sent (in addition to the InterestedUsers list, which includes any
7699 developers who made Changes that went into this build). It is a good
7700 idea to create a small mailing list and deliver to that, then let
7701 subscribers come and go as they please.
7704 (string). A string to be used as the subject line of the message.
7705 @code{%(builder)s} will be replaced with the name of the builder which
7706 provoked the message.
7709 (string). Default to 'all'. One of:
7712 Send mail about all builds, bothpassing and failing
7714 Only send mail about builds which fail
7716 Only send mail about a build which failed when the previous build has passed.
7717 If your builds usually pass, then this will only send mail when a problem
7722 (list of strings). A list of builder names for which mail should be
7723 sent. Defaults to None (send mail for all builds). Use either builders
7724 or categories, but not both.
7727 (list of strings). A list of category names to serve status
7728 information for. Defaults to None (all categories). Use either
7729 builders or categories, but not both.
7732 (boolean). If True, include all build logs as attachments to the
7733 messages. These can be quite large. This can also be set to a list of
7734 log names, to send a subset of the logs. Defaults to False.
7737 (string). The host to which the outbound SMTP connection should be
7738 made. Defaults to 'localhost'
7741 (implementor of @code{IEmailLookup}). Object which provides
7742 IEmailLookup, which is responsible for mapping User names (which come
7743 from the VC system) into valid email addresses. If not provided, the
7744 notifier will only be able to send mail to the addresses in the
7745 extraRecipients list. Most of the time you can use a simple Domain
7746 instance. As a shortcut, you can pass as string: this will be treated
7747 as if you had provided Domain(str). For example,
7748 lookup='twistedmatrix.com' will allow mail to be sent to all
7749 developers whose SVN usernames match their twistedmatrix.com account
7750 names. See buildbot/status/mail.py for more details.
7753 This is a optional function that can be used to generate a custom mail
7754 message. The customMesg function takes a single dict and must return a
7755 tuple containing the message text and type ('html' or 'plain'). Below is a list
7756 of availale keys in the dict passed to customMesg:
7760 (str) Name of the builder that generated this event.
7762 (str) Name of the project.
7764 (str) Mode set in MailNotifier. (failing, passing, problem).
7766 (str) Builder result as a string. 'success', 'warnings', 'failure', 'skipped', or 'exception'
7768 (str) URL to build page.
7770 (str) URL to buildbot main page.
7772 (str) Build text from build.getText().
7776 (str) Build reason from build.getReason().
7777 @item responsibleUsers
7778 (List of str) List of responsible users.
7780 (str) Name of branch used. If no SourceStamp exists branch
7783 (str) Name of revision used. If no SourceStamp exists revision
7786 (str) Name of patch used. If no SourceStamp exists patch
7789 (list of objs) List of change objects from SourceStamp. A change
7790 object has the following useful information:
7793 (str) who made this change
7795 (str) what VC revision is this change
7797 (str) on what branch did this change occur
7799 (str) when did this change occur
7801 (list of str) what files were affected in this change
7803 (str) comments reguarding the change.
7805 The functions asText and asHTML return a list of strings with
7806 the above information formatted.
7808 (List of Tuples) List of tuples where each tuple contains the log name, log url,
7809 and log contents as a list of strings.
7813 @node IRC Bot, PBListener, MailNotifier, Status Delivery
7817 @stindex buildbot.status.words.IRC
7820 The @code{buildbot.status.words.IRC} status target creates an IRC bot
7821 which will attach to certain channels and be available for status
7822 queries. It can also be asked to announce builds as they occur, or be
7826 from buildbot.status import words
7827 irc = words.IRC("irc.example.org", "botnickname",
7828 channels=["channel1", "channel2"],
7829 password="mysecretpassword",
7832 'successToFailure': 1,
7833 'failureToSuccess': 1,
7835 c['status'].append(irc)
7838 Take a look at the docstring for @code{words.IRC} for more details on
7839 configuring this service. The @code{password} argument, if provided,
7840 will be sent to Nickserv to claim the nickname: some IRC servers will
7841 not allow clients to send private messages until they have logged in
7844 To use the service, you address messages at the buildbot, either
7845 normally (@code{botnickname: status}) or with private messages
7846 (@code{/msg botnickname status}). The buildbot will respond in kind.
7848 Some of the commands currently available:
7853 Emit a list of all configured builders
7854 @item status BUILDER
7855 Announce the status of a specific Builder: what it is doing right now.
7857 Announce the status of all Builders
7859 If the given Builder is currently running, wait until the Build is
7860 finished and then announce the results.
7862 Return the results of the last build to run on the given Builder.
7864 Join the given IRC channel
7866 Leave the given IRC channel
7867 @item notify on|off|list EVENT
7868 Report events relating to builds. If the command is issued as a
7869 private message, then the report will be sent back as a private
7870 message to the user who issued the command. Otherwise, the report
7871 will be sent to the channel. Available events to be notified are:
7877 A build has finished
7879 A build finished successfully
7883 A build generated and exception
7885 The previous build was x, but this one is Y, where x and Y are each
7886 one of success, warnings, failure, exception (except Y is
7887 capitalized). For example: successToFailure will notify if the
7888 previous build was successful, but this one failed
7892 Describe a command. Use @code{help commands} to get a list of known
7895 Announce the URL of the Buildbot's home page.
7897 Announce the version of this Buildbot.
7900 Additionally, the config file may specify default notification options
7901 as shown in the example earlier.
7903 If the @code{allowForce=True} option was used, some addtional commands
7907 @item force build BUILDER REASON
7908 Tell the given Builder to start a build of the latest code. The user
7909 requesting the build and REASON are recorded in the Build status. The
7910 buildbot will announce the build's status when it finishes.
7912 @item stop build BUILDER REASON
7913 Terminate any running build in the given Builder. REASON will be added
7914 to the build status to explain why it was stopped. You might use this
7915 if you committed a bug, corrected it right away, and don't want to
7916 wait for the first build (which is destined to fail) to complete
7917 before starting the second (hopefully fixed) build.
7920 @node PBListener, Writing New Status Plugins, IRC Bot, Status Delivery
7924 @stindex buildbot.status.client.PBListener
7928 import buildbot.status.client
7929 pbl = buildbot.status.client.PBListener(port=int, user=str,
7931 c['status'].append(pbl)
7934 This sets up a PB listener on the given TCP port, to which a PB-based
7935 status client can connect and retrieve status information.
7936 @code{buildbot statusgui} (@pxref{statusgui}) is an example of such a
7937 status client. The @code{port} argument can also be a strports
7938 specification string.
7940 @node Writing New Status Plugins, , PBListener, Status Delivery
7941 @section Writing New Status Plugins
7943 TODO: this needs a lot more examples
7945 Each status plugin is an object which provides the
7946 @code{twisted.application.service.IService} interface, which creates a
7947 tree of Services with the buildmaster at the top [not strictly true].
7948 The status plugins are all children of an object which implements
7949 @code{buildbot.interfaces.IStatus}, the main status object. From this
7950 object, the plugin can retrieve anything it wants about current and
7951 past builds. It can also subscribe to hear about new and upcoming
7954 Status plugins which only react to human queries (like the Waterfall
7955 display) never need to subscribe to anything: they are idle until
7956 someone asks a question, then wake up and extract the information they
7957 need to answer it, then they go back to sleep. Plugins which need to
7958 act spontaneously when builds complete (like the MailNotifier plugin)
7959 need to subscribe to hear about new builds.
7961 If the status plugin needs to run network services (like the HTTP
7962 server used by the Waterfall plugin), they can be attached as Service
7963 children of the plugin itself, using the @code{IServiceCollection}
7968 @node Command-line tool, Resources, Status Delivery, Top
7969 @chapter Command-line tool
7971 The @command{buildbot} command-line tool can be used to start or stop a
7972 buildmaster or buildbot, and to interact with a running buildmaster.
7973 Some of its subcommands are intended for buildmaster admins, while
7974 some are for developers who are editing the code that the buildbot is
7978 * Administrator Tools::
7981 * .buildbot config directory::
7984 @node Administrator Tools, Developer Tools, Command-line tool, Command-line tool
7985 @section Administrator Tools
7987 The following @command{buildbot} sub-commands are intended for
7988 buildmaster administrators:
7990 @heading create-master
7992 This creates a new directory and populates it with files that allow it
7993 to be used as a buildmaster's base directory.
7996 buildbot create-master BASEDIR
7999 @heading create-slave
8001 This creates a new directory and populates it with files that let it
8002 be used as a buildslave's base directory. You must provide several
8003 arguments, which are used to create the initial @file{buildbot.tac}
8007 buildbot create-slave @var{BASEDIR} @var{MASTERHOST}:@var{PORT} @var{SLAVENAME} @var{PASSWORD}
8012 This starts a buildmaster or buildslave which was already created in
8013 the given base directory. The daemon is launched in the background,
8014 with events logged to a file named @file{twistd.log}.
8017 buildbot start BASEDIR
8022 This terminates the daemon (either buildmaster or buildslave) running
8023 in the given directory.
8026 buildbot stop BASEDIR
8031 This sends a SIGHUP to the buildmaster running in the given directory,
8032 which causes it to re-read its @file{master.cfg} file.
8035 buildbot sighup BASEDIR
8038 @node Developer Tools, Other Tools, Administrator Tools, Command-line tool
8039 @section Developer Tools
8041 These tools are provided for use by the developers who are working on
8042 the code that the buildbot is monitoring.
8050 @node statuslog, statusgui, Developer Tools, Developer Tools
8051 @subsection statuslog
8054 buildbot statuslog --master @var{MASTERHOST}:@var{PORT}
8057 This command starts a simple text-based status client, one which just
8058 prints out a new line each time an event occurs on the buildmaster.
8060 The @option{--master} option provides the location of the
8061 @code{buildbot.status.client.PBListener} status port, used to deliver
8062 build information to realtime status clients. The option is always in
8063 the form of a string, with hostname and port number separated by a
8064 colon (@code{HOSTNAME:PORTNUM}). Note that this port is @emph{not} the
8065 same as the slaveport (although a future version may allow the same
8066 port number to be used for both purposes). If you get an error message
8067 to the effect of ``Failure: twisted.cred.error.UnauthorizedLogin:'',
8068 this may indicate that you are connecting to the slaveport rather than
8069 a @code{PBListener} port.
8071 The @option{--master} option can also be provided by the
8072 @code{masterstatus} name in @file{.buildbot/options} (@pxref{.buildbot
8075 @node statusgui, try, statuslog, Developer Tools
8076 @subsection statusgui
8080 If you have set up a PBListener (@pxref{PBListener}), you will be able
8081 to monitor your Buildbot using a simple Gtk+ application invoked with
8082 the @code{buildbot statusgui} command:
8085 buildbot statusgui --master @var{MASTERHOST}:@var{PORT}
8088 This command starts a simple Gtk+-based status client, which contains
8089 a few boxes for each Builder that change color as events occur. It
8090 uses the same @option{--master} argument as the @command{buildbot
8091 statuslog} command (@pxref{statuslog}).
8093 @node try, , statusgui, Developer Tools
8096 This lets a developer to ask the question ``What would happen if I
8097 committed this patch right now?''. It runs the unit test suite (across
8098 multiple build platforms) on the developer's current code, allowing
8099 them to make sure they will not break the tree when they finally
8100 commit their changes.
8102 The @command{buildbot try} command is meant to be run from within a
8103 developer's local tree, and starts by figuring out the base revision
8104 of that tree (what revision was current the last time the tree was
8105 updated), and a patch that can be applied to that revision of the tree
8106 to make it match the developer's copy. This (revision, patch) pair is
8107 then sent to the buildmaster, which runs a build with that
8108 SourceStamp. If you want, the tool will emit status messages as the
8109 builds run, and will not terminate until the first failure has been
8110 detected (or the last success).
8112 There is an alternate form which accepts a pre-made patch file
8113 (typically the output of a command like 'svn diff'). This ``--diff''
8114 form does not require a local tree to run from. See @xref{try --diff}.
8116 For this command to work, several pieces must be in place:
8119 @heading TryScheduler
8121 @slindex buildbot.scheduler.Try_Jobdir
8122 @slindex buildbot.scheduler.Try_Userpass
8124 The buildmaster must have a @code{scheduler.Try} instance in
8125 the config file's @code{c['schedulers']} list. This lets the
8126 administrator control who may initiate these ``trial'' builds, which
8127 branches are eligible for trial builds, and which Builders should be
8130 The @code{TryScheduler} has various means to accept build requests:
8131 all of them enforce more security than the usual buildmaster ports do.
8132 Any source code being built can be used to compromise the buildslave
8133 accounts, but in general that code must be checked out from the VC
8134 repository first, so only people with commit privileges can get
8135 control of the buildslaves. The usual force-build control channels can
8136 waste buildslave time but do not allow arbitrary commands to be
8137 executed by people who don't have those commit privileges. However,
8138 the source code patch that is provided with the trial build does not
8139 have to go through the VC system first, so it is important to make
8140 sure these builds cannot be abused by a non-committer to acquire as
8141 much control over the buildslaves as a committer has. Ideally, only
8142 developers who have commit access to the VC repository would be able
8143 to start trial builds, but unfortunately the buildmaster does not, in
8144 general, have access to VC system's user list.
8146 As a result, the @code{TryScheduler} requires a bit more
8147 configuration. There are currently two ways to set this up:
8152 This approach creates a command queue directory, called the
8153 ``jobdir'', in the buildmaster's working directory. The buildmaster
8154 admin sets the ownership and permissions of this directory to only
8155 grant write access to the desired set of developers, all of whom must
8156 have accounts on the machine. The @code{buildbot try} command creates
8157 a special file containing the source stamp information and drops it in
8158 the jobdir, just like a standard maildir. When the buildmaster notices
8159 the new file, it unpacks the information inside and starts the builds.
8161 The config file entries used by 'buildbot try' either specify a local
8162 queuedir (for which write and mv are used) or a remote one (using scp
8165 The advantage of this scheme is that it is quite secure, the
8166 disadvantage is that it requires fiddling outside the buildmaster
8167 config (to set the permissions on the jobdir correctly). If the
8168 buildmaster machine happens to also house the VC repository, then it
8169 can be fairly easy to keep the VC userlist in sync with the
8170 trial-build userlist. If they are on different machines, this will be
8171 much more of a hassle. It may also involve granting developer accounts
8172 on a machine that would not otherwise require them.
8174 To implement this, the buildslave invokes 'ssh -l username host
8175 buildbot tryserver ARGS', passing the patch contents over stdin. The
8176 arguments must include the inlet directory and the revision
8179 @item user+password (PB)
8181 In this approach, each developer gets a username/password pair, which
8182 are all listed in the buildmaster's configuration file. When the
8183 developer runs @code{buildbot try}, their machine connects to the
8184 buildmaster via PB and authenticates themselves using that username
8185 and password, then sends a PB command to start the trial build.
8187 The advantage of this scheme is that the entire configuration is
8188 performed inside the buildmaster's config file. The disadvantages are
8189 that it is less secure (while the ``cred'' authentication system does
8190 not expose the password in plaintext over the wire, it does not offer
8191 most of the other security properties that SSH does). In addition, the
8192 buildmaster admin is responsible for maintaining the username/password
8193 list, adding and deleting entries as developers come and go.
8198 For example, to set up the ``jobdir'' style of trial build, using a
8199 command queue directory of @file{MASTERDIR/jobdir} (and assuming that
8200 all your project developers were members of the @code{developers} unix
8201 group), you would first create that directory (with @command{mkdir
8202 MASTERDIR/jobdir MASTERDIR/jobdir/new MASTERDIR/jobdir/cur
8203 MASTERDIR/jobdir/tmp; chgrp developers MASTERDIR/jobdir
8204 MASTERDIR/jobdir/*; chmod g+rwx,o-rwx MASTERDIR/jobdir
8205 MASTERDIR/jobdir/*}), and then use the following scheduler in the
8206 buildmaster's config file:
8209 from buildbot.scheduler import Try_Jobdir
8210 s = Try_Jobdir("try1", ["full-linux", "full-netbsd", "full-OSX"],
8212 c['schedulers'] = [s]
8215 Note that you must create the jobdir before telling the buildmaster to
8216 use this configuration, otherwise you will get an error. Also remember
8217 that the buildmaster must be able to read and write to the jobdir as
8218 well. Be sure to watch the @file{twistd.log} file (@pxref{Logfiles})
8219 as you start using the jobdir, to make sure the buildmaster is happy
8222 To use the username/password form of authentication, create a
8223 @code{Try_Userpass} instance instead. It takes the same
8224 @code{builderNames} argument as the @code{Try_Jobdir} form, but
8225 accepts an addtional @code{port} argument (to specify the TCP port to
8226 listen on) and a @code{userpass} list of username/password pairs to
8227 accept. Remember to use good passwords for this: the security of the
8228 buildslave accounts depends upon it:
8231 from buildbot.scheduler import Try_Userpass
8232 s = Try_Userpass("try2", ["full-linux", "full-netbsd", "full-OSX"],
8233 port=8031, userpass=[("alice","pw1"), ("bob", "pw2")] )
8234 c['schedulers'] = [s]
8237 Like most places in the buildbot, the @code{port} argument takes a
8238 strports specification. See @code{twisted.application.strports} for
8242 @heading locating the master
8244 The @command{try} command needs to be told how to connect to the
8245 @code{TryScheduler}, and must know which of the authentication
8246 approaches described above is in use by the buildmaster. You specify
8247 the approach by using @option{--connect=ssh} or @option{--connect=pb}
8248 (or @code{try_connect = 'ssh'} or @code{try_connect = 'pb'} in
8249 @file{.buildbot/options}).
8251 For the PB approach, the command must be given a @option{--master}
8252 argument (in the form HOST:PORT) that points to TCP port that you
8253 picked in the @code{Try_Userpass} scheduler. It also takes a
8254 @option{--username} and @option{--passwd} pair of arguments that match
8255 one of the entries in the buildmaster's @code{userpass} list. These
8256 arguments can also be provided as @code{try_master},
8257 @code{try_username}, and @code{try_password} entries in the
8258 @file{.buildbot/options} file.
8260 For the SSH approach, the command must be given @option{--tryhost},
8261 @option{--username}, and optionally @option{--password} (TODO:
8262 really?) to get to the buildmaster host. It must also be given
8263 @option{--trydir}, which points to the inlet directory configured
8264 above. The trydir can be relative to the user's home directory, but
8265 most of the time you will use an explicit path like
8266 @file{~buildbot/project/trydir}. These arguments can be provided in
8267 @file{.buildbot/options} as @code{try_host}, @code{try_username},
8268 @code{try_password}, and @code{try_dir}.
8270 In addition, the SSH approach needs to connect to a PBListener status
8271 port, so it can retrieve and report the results of the build (the PB
8272 approach uses the existing connection to retrieve status information,
8273 so this step is not necessary). This requires a @option{--master}
8274 argument, or a @code{masterstatus} entry in @file{.buildbot/options},
8275 in the form of a HOSTNAME:PORT string.
8278 @heading choosing the Builders
8280 A trial build is performed on multiple Builders at the same time, and
8281 the developer gets to choose which Builders are used (limited to a set
8282 selected by the buildmaster admin with the TryScheduler's
8283 @code{builderNames=} argument). The set you choose will depend upon
8284 what your goals are: if you are concerned about cross-platform
8285 compatibility, you should use multiple Builders, one from each
8286 platform of interest. You might use just one builder if that platform
8287 has libraries or other facilities that allow better test coverage than
8288 what you can accomplish on your own machine, or faster test runs.
8290 The set of Builders to use can be specified with multiple
8291 @option{--builder} arguments on the command line. It can also be
8292 specified with a single @code{try_builders} option in
8293 @file{.buildbot/options} that uses a list of strings to specify all
8297 try_builders = ["full-OSX", "full-win32", "full-linux"]
8300 @heading specifying the VC system
8302 The @command{try} command also needs to know how to take the
8303 developer's current tree and extract the (revision, patch)
8304 source-stamp pair. Each VC system uses a different process, so you
8305 start by telling the @command{try} command which VC system you are
8306 using, with an argument like @option{--vc=cvs} or @option{--vc=tla}.
8307 This can also be provided as @code{try_vc} in
8308 @file{.buildbot/options}.
8310 The following names are recognized: @code{cvs} @code{svn} @code{baz}
8311 @code{tla} @code{hg} @code{darcs}
8314 @heading finding the top of the tree
8316 Some VC systems (notably CVS and SVN) track each directory
8317 more-or-less independently, which means the @command{try} command
8318 needs to move up to the top of the project tree before it will be able
8319 to construct a proper full-tree patch. To accomplish this, the
8320 @command{try} command will crawl up through the parent directories
8321 until it finds a marker file. The default name for this marker file is
8322 @file{.buildbot-top}, so when you are using CVS or SVN you should
8323 @code{touch .buildbot-top} from the top of your tree before running
8324 @command{buildbot try}. Alternatively, you can use a filename like
8325 @file{ChangeLog} or @file{README}, since many projects put one of
8326 these files in their top-most directory (and nowhere else). To set
8327 this filename, use @option{--try-topfile=ChangeLog}, or set it in the
8328 options file with @code{try_topfile = 'ChangeLog'}.
8330 You can also manually set the top of the tree with
8331 @option{--try-topdir=~/trees/mytree}, or @code{try_topdir =
8332 '~/trees/mytree'}. If you use @code{try_topdir}, in a
8333 @file{.buildbot/options} file, you will need a separate options file
8334 for each tree you use, so it may be more convenient to use the
8335 @code{try_topfile} approach instead.
8337 Other VC systems which work on full projects instead of individual
8338 directories (tla, baz, darcs, monotone, mercurial, git) do not require
8339 @command{try} to know the top directory, so the @option{--try-topfile}
8340 and @option{--try-topdir} arguments will be ignored.
8341 @c is this true? I think I currently require topdirs all the time.
8343 If the @command{try} command cannot find the top directory, it will
8344 abort with an error message.
8346 @heading determining the branch name
8348 Some VC systems record the branch information in a way that ``try''
8349 can locate it, in particular Arch (both @command{tla} and
8350 @command{baz}). For the others, if you are using something other than
8351 the default branch, you will have to tell the buildbot which branch
8352 your tree is using. You can do this with either the @option{--branch}
8353 argument, or a @option{try_branch} entry in the
8354 @file{.buildbot/options} file.
8356 @heading determining the revision and patch
8358 Each VC system has a separate approach for determining the tree's base
8359 revision and computing a patch.
8365 @command{try} pretends that the tree is up to date. It converts the
8366 current time into a @code{-D} time specification, uses it as the base
8367 revision, and computes the diff between the upstream tree as of that
8368 point in time versus the current contents. This works, more or less,
8369 but requires that the local clock be in reasonably good sync with the
8373 @command{try} does a @code{svn status -u} to find the latest
8374 repository revision number (emitted on the last line in the ``Status
8375 against revision: NN'' message). It then performs an @code{svn diff
8376 -rNN} to find out how your tree differs from the repository version,
8377 and sends the resulting patch to the buildmaster. If your tree is not
8378 up to date, this will result in the ``try'' tree being created with
8379 the latest revision, then @emph{backwards} patches applied to bring it
8380 ``back'' to the version you actually checked out (plus your actual
8381 code changes), but this will still result in the correct tree being
8385 @command{try} does a @code{baz tree-id} to determine the
8386 fully-qualified version and patch identifier for the tree
8387 (ARCHIVE/VERSION--patch-NN), and uses the VERSION--patch-NN component
8388 as the base revision. It then does a @code{baz diff} to obtain the
8392 @command{try} does a @code{tla tree-version} to get the
8393 fully-qualified version identifier (ARCHIVE/VERSION), then takes the
8394 first line of @code{tla logs --reverse} to figure out the base
8395 revision. Then it does @code{tla changes --diffs} to obtain the patch.
8398 @code{darcs changes --context} emits a text file that contains a list
8399 of all patches back to and including the last tag was made. This text
8400 file (plus the location of a repository that contains all these
8401 patches) is sufficient to re-create the tree. Therefore the contents
8402 of this ``context'' file @emph{are} the revision stamp for a
8403 Darcs-controlled source tree.
8405 So @command{try} does a @code{darcs changes --context} to determine
8406 what your tree's base revision is, and then does a @code{darcs diff
8407 -u} to compute the patch relative to that revision.
8410 @code{hg identify} emits a short revision ID (basically a truncated
8411 SHA1 hash of the current revision's contents), which is used as the
8412 base revision. @code{hg diff} then provides the patch relative to that
8413 revision. For @command{try} to work, your working directory must only
8414 have patches that are available from the same remotely-available
8415 repository that the build process' @code{step.Mercurial} will use.
8418 @code{git branch -v} lists all the branches available in the local
8419 repository along with the revision ID it points to and a short summary
8420 of the last commit. The line containing the currently checked out
8421 branch begins with '* ' (star and space) while all the others start
8422 with ' ' (two spaces). @command{try} scans for this line and extracts
8423 the branch name and revision from it. Then it generates a diff against
8425 @c TODO: I'm not sure if this actually works the way it's intended
8426 @c since the extracted base revision might not actually exist in the
8427 @c upstream repository. Perhaps we need to add a --remote option to
8428 @c specify the remote tracking branch to generate a diff against.
8433 @heading waiting for results
8435 If you provide the @option{--wait} option (or @code{try_wait = True}
8436 in @file{.buildbot/options}), the @command{buildbot try} command will
8437 wait until your changes have either been proven good or bad before
8438 exiting. Unless you use the @option{--quiet} option (or
8439 @code{try_quiet=True}), it will emit a progress message every 60
8440 seconds until the builds have completed.
8446 @node try --diff, , try, try
8447 @subsubsection try --diff
8449 Sometimes you might have a patch from someone else that you want to
8450 submit to the buildbot. For example, a user may have created a patch
8451 to fix some specific bug and sent it to you by email. You've inspected
8452 the patch and suspect that it might do the job (and have at least
8453 confirmed that it doesn't do anything evil). Now you want to test it
8456 One approach would be to check out a new local tree, apply the patch,
8457 run your local tests, then use ``buildbot try'' to run the tests on
8458 other platforms. An alternate approach is to use the @command{buildbot
8459 try --diff} form to have the buildbot test the patch without using a
8462 This form takes a @option{--diff} argument which points to a file that
8463 contains the patch you want to apply. By default this patch will be
8464 applied to the TRUNK revision, but if you give the optional
8465 @option{--baserev} argument, a tree of the given revision will be used
8466 as a starting point instead of TRUNK.
8468 You can also use @command{buildbot try --diff=-} to read the patch
8471 Each patch has a ``patchlevel'' associated with it. This indicates the
8472 number of slashes (and preceding pathnames) that should be stripped
8473 before applying the diff. This exactly corresponds to the @option{-p}
8474 or @option{--strip} argument to the @command{patch} utility. By
8475 default @command{buildbot try --diff} uses a patchlevel of 0, but you
8476 can override this with the @option{-p} argument.
8478 When you use @option{--diff}, you do not need to use any of the other
8479 options that relate to a local tree, specifically @option{--vc},
8480 @option{--try-topfile}, or @option{--try-topdir}. These options will
8481 be ignored. Of course you must still specify how to get to the
8482 buildmaster (with @option{--connect}, @option{--tryhost}, etc).
8485 @node Other Tools, .buildbot config directory, Developer Tools, Command-line tool
8486 @section Other Tools
8488 These tools are generally used by buildmaster administrators.
8495 @node sendchange, debugclient, Other Tools, Other Tools
8496 @subsection sendchange
8498 This command is used to tell the buildmaster about source changes. It
8499 is intended to be used from within a commit script, installed on the
8500 VC server. It requires that you have a PBChangeSource
8501 (@pxref{PBChangeSource}) running in the buildmaster (by being set in
8502 @code{c['change_source']}).
8506 buildbot sendchange --master @var{MASTERHOST}:@var{PORT} --username @var{USER} @var{FILENAMES..}
8509 There are other (optional) arguments which can influence the
8510 @code{Change} that gets submitted:
8514 This provides the (string) branch specifier. If omitted, it defaults
8515 to None, indicating the ``default branch''. All files included in this
8516 Change must be on the same branch.
8519 This provides the (string) category specifier. If omitted, it defaults
8520 to None, indicating ``no category''. The category property is used
8521 by Schedulers to filter what changes they listen to.
8523 @item --revision_number
8524 This provides a (numeric) revision number for the change, used for VC systems
8525 that use numeric transaction numbers (like Subversion).
8528 This provides a (string) revision specifier, for VC systems that use
8529 strings (Arch would use something like patch-42 etc).
8531 @item --revision_file
8532 This provides a filename which will be opened and the contents used as
8533 the revision specifier. This is specifically for Darcs, which uses the
8534 output of @command{darcs changes --context} as a revision specifier.
8535 This context file can be a couple of kilobytes long, spanning a couple
8536 lines per patch, and would be a hassle to pass as a command-line
8540 This provides the change comments as a single argument. You may want
8541 to use @option{--logfile} instead.
8544 This instructs the tool to read the change comments from the given
8545 file. If you use @code{-} as the filename, the tool will read the
8546 change comments from stdin.
8550 @node debugclient, , sendchange, Other Tools
8551 @subsection debugclient
8554 buildbot debugclient --master @var{MASTERHOST}:@var{PORT} --passwd @var{DEBUGPW}
8557 This launches a small Gtk+/Glade-based debug tool, connecting to the
8558 buildmaster's ``debug port''. This debug port shares the same port
8559 number as the slaveport (@pxref{Setting the slaveport}), but the
8560 @code{debugPort} is only enabled if you set a debug password in the
8561 buildmaster's config file (@pxref{Debug options}). The
8562 @option{--passwd} option must match the @code{c['debugPassword']}
8565 @option{--master} can also be provided in @file{.debug/options} by the
8566 @code{master} key. @option{--passwd} can be provided by the
8567 @code{debugPassword} key.
8569 The @code{Connect} button must be pressed before any of the other
8570 buttons will be active. This establishes the connection to the
8571 buildmaster. The other sections of the tool are as follows:
8575 Forces the buildmaster to reload its @file{master.cfg} file. This is
8576 equivalent to sending a SIGHUP to the buildmaster, but can be done
8577 remotely through the debug port. Note that it is a good idea to be
8578 watching the buildmaster's @file{twistd.log} as you reload the config
8579 file, as any errors which are detected in the config file will be
8583 (not yet implemented). The idea here is to use Twisted's ``rebuild''
8584 facilities to replace the buildmaster's running code with a new
8585 version. Even if this worked, it would only be used by buildbot
8589 This locates a @code{words.IRC} status target and causes it to emit a
8590 message on all the channels to which it is currently connected. This
8591 was used to debug a problem in which the buildmaster lost the
8592 connection to the IRC server and did not attempt to reconnect.
8595 This allows you to inject a Change, just as if a real one had been
8596 delivered by whatever VC hook you are using. You can set the name of
8597 the committed file and the name of the user who is doing the commit.
8598 Optionally, you can also set a revision for the change. If the
8599 revision you provide looks like a number, it will be sent as an
8600 integer, otherwise it will be sent as a string.
8603 This lets you force a Builder (selected by name) to start a build of
8604 the current source tree.
8607 (obsolete). This was used to manually set the status of the given
8608 Builder, but the status-assignment code was changed in an incompatible
8609 way and these buttons are no longer meaningful.
8614 @node .buildbot config directory, , Other Tools, Command-line tool
8615 @section .buildbot config directory
8617 Many of the @command{buildbot} tools must be told how to contact the
8618 buildmaster that they interact with. This specification can be
8619 provided as a command-line argument, but most of the time it will be
8620 easier to set them in an ``options'' file. The @command{buildbot}
8621 command will look for a special directory named @file{.buildbot},
8622 starting from the current directory (where the command was run) and
8623 crawling upwards, eventually looking in the user's home directory. It
8624 will look for a file named @file{options} in this directory, and will
8625 evaluate it as a python script, looking for certain names to be set.
8626 You can just put simple @code{name = 'value'} pairs in this file to
8629 For a description of the names used in this file, please see the
8630 documentation for the individual @command{buildbot} sub-commands. The
8631 following is a brief sample of what this file's contents could be.
8634 # for status-reading tools
8635 masterstatus = 'buildbot.example.org:12345'
8636 # for 'sendchange' or the debug port
8637 master = 'buildbot.example.org:18990'
8638 debugPassword = 'eiv7Po'
8643 Location of the @code{client.PBListener} status port, used by
8644 @command{statuslog} and @command{statusgui}.
8647 Location of the @code{debugPort} (for @command{debugclient}). Also the
8648 location of the @code{pb.PBChangeSource} (for @command{sendchange}).
8649 Usually shares the slaveport, but a future version may make it
8650 possible to have these listen on a separate port number.
8653 Must match the value of @code{c['debugPassword']}, used to protect the
8654 debug port, for the @command{debugclient} command.
8657 Provides a default username for the @command{sendchange} command.
8662 The following options are used by the @code{buildbot try} command
8667 This specifies how the ``try'' command should deliver its request to
8668 the buildmaster. The currently accepted values are ``ssh'' and ``pb''.
8670 Which builders should be used for the ``try'' build.
8672 This specifies the version control system being used.
8674 This indicates that the current tree is on a non-trunk branch.
8677 Use @code{try_topdir} to explicitly indicate the top of your working
8678 tree, or @code{try_topfile} to name a file that will only be found in
8679 that top-most directory.
8684 When try_connect is ``ssh'', the command will pay attention to
8685 @code{try_host}, @code{try_username}, and @code{try_dir}.
8690 Instead, when @code{try_connect} is ``pb'', the command will pay
8691 attention to @code{try_username}, @code{try_password}, and
8696 @code{try_wait} and @code{masterstatus} are used to ask the ``try''
8697 command to wait for the requested build to complete.
8703 @node Resources, Developer's Appendix, Command-line tool, Top
8706 The Buildbot's home page is at @uref{http://buildbot.sourceforge.net/}
8708 For configuration questions and general discussion, please use the
8709 @code{buildbot-devel} mailing list. The subscription instructions and
8710 archives are available at
8711 @uref{http://lists.sourceforge.net/lists/listinfo/buildbot-devel}
8713 @node Developer's Appendix, Index of Useful Classes, Resources, Top
8714 @unnumbered Developer's Appendix
8716 This appendix contains random notes about the implementation of the
8717 Buildbot, and is likely to only be of use to people intending to
8718 extend the Buildbot's internals.
8720 The buildmaster consists of a tree of Service objects, which is shaped
8725 ChangeMaster (in .change_svc)
8726 [IChangeSource instances]
8727 [IScheduler instances] (in .schedulers)
8728 BotMaster (in .botmaster)
8729 [IBuildSlave instances]
8730 [IStatusTarget instances] (in .statusTargets)
8733 The BotMaster has a collection of Builder objects as values of its
8734 @code{.builders} dictionary.
8737 @node Index of Useful Classes, Index of master.cfg keys, Developer's Appendix, Top
8738 @unnumbered Index of Useful Classes
8740 This is a list of all user-visible classes. There are the ones that
8741 are useful in @file{master.cfg}, the buildmaster's configuration file.
8742 Classes that are not listed here are generally internal things that
8743 admins are unlikely to have much use for.
8746 @heading Change Sources
8749 @heading Schedulers and Locks
8752 @heading Build Factories
8755 @heading Build Steps
8758 @c undocumented steps
8759 @bsindex buildbot.steps.source.Git
8760 @bsindex buildbot.steps.maxq.MaxQ
8763 @heading Status Targets
8766 @c TODO: undocumented targets
8768 @node Index of master.cfg keys, Index, Index of Useful Classes, Top
8769 @unnumbered Index of master.cfg keys
8771 This is a list of all of the significant keys in master.cfg . Recall
8772 that master.cfg is effectively a small python program with exactly one
8773 responsibility: create a dictionary named @code{BuildmasterConfig}.
8774 The keys of this dictionary are listed here. The beginning of the
8775 master.cfg file typically starts with something like:
8778 BuildmasterConfig = c = @{@}
8781 Therefore a config key of @code{change_source} will usually appear in
8782 master.cfg as @code{c['change_source']}.
8787 @node Index, , Index of master.cfg keys, Top