[Buildbot-commits] buildbot/docs buildbot.texinfo,1.24,1.25
Brian Warner
warner at users.sourceforge.net
Tue Oct 25 01:26:13 UTC 2005
Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv8323/docs
Modified Files:
buildbot.texinfo
Log Message:
Revision: arch at buildbot.sf.net--2004/buildbot--dev--0--patch-382
Creator: Brian Warner <warner at lothar.com>
update manual, add --branch to 'buildbot sendchange'
* docs/buildbot.texinfo: update lots of stuff
* buildbot/scripts/runner.py (sendchange): add a --branch argument
to the 'buildbot sendchange' command
* buildbot/clients/sendchange.py (Sender.send): same
* buildbot/changes/pb.py (ChangePerspective): same
* buildbot/test/test_changes.py (Sender.testSender): test it
Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -d -r1.24 -r1.25
--- buildbot.texinfo 24 Oct 2005 22:42:03 -0000 1.24
+++ buildbot.texinfo 25 Oct 2005 01:26:11 -0000 1.25
@@ -281,9 +281,12 @@
a minimum.
In general, having more visibility into the project is always good,
-and automation makes it easier for to do the right thing. When
-everyone can see the status of the project, developers are encouraged
-to keep the tree in good working order.
+and automation makes it easier for developers to do the right thing.
+When everyone can see the status of the project, developers are
+encouraged to keep the tree in good working order. Unit tests that
+aren't run on a regular basis tend to suffer from bitrot just like
+code does: exercising them on a regular basis helps to keep them
+functioning and useful.
The current version of the Buildbot is additionally targeted at
distributed free-software projects, where resources and platforms are
@@ -420,27 +423,29 @@
@item
Python: http://www.python.org
-Buildbot requires python-2.2 or later, and is primarily developed against
-python-2.3. The buildmaster uses generators, a feature which is not
-available in python-2.1, and both master and slave require a version of
-Twisted which only works with python-2.2 or later. Certain features (like
-the inclusion of build logs in status emails) require python-2.2.2 or
-later.
+Buildbot requires python-2.2 or later, and is primarily developed
+against python-2.3. The buildmaster uses generators, a feature which
+is not available in python-2.1, and both master and slave require a
+version of Twisted which only works with python-2.2 or later. Certain
+features (like the inclusion of build logs in status emails) require
+python-2.2.2 or later. The IRC ``force build'' command requires
+python-2.3 (for the shlex.split function).
@item
Twisted: http://twistedmatrix.com
Both the buildmaster and the buildslaves require Twisted-1.3.0 or
-later. They have been briefly tested against Twisted-1.2.0, and might
-even work with Twisted-1.1.0, but 1.3.0 is the version that has
-received the most testing.
+later. It has been mainly developed against Twisted-2.0.1, but has
+been tested against Twisted-2.1.0 (the most recent as of this
+writing), and might even work on versions as old as Twisted-1.1.0, but
+as always the most recent version is recommended.
-They run against Twisted-2.0.0 as well, albeit with a number of
-warnings about the use of deprecated features. If you use Twisted-2.0,
-you'll need at least "Twisted" (the core package), and you'll also
-want TwistedMail, TwistedWeb, and TwistedWords (for sending email,
-serving a web status page, and delivering build status via IRC,
-respectively).
+Twisted-1.3.0 and earlier were released as a single monolithic
+package. When you run Buildbot against Twisted-2.0.0 or later (which
+are split into a number of smaller subpackages), you'll need at least
+"Twisted" (the core package), and you'll also want TwistedMail,
+TwistedWeb, and TwistedWords (for sending email, serving a web status
+page, and delivering build status via IRC, respectively).
@end itemize
Certain other packages may be useful on the system running the
@@ -458,6 +463,10 @@
@end itemize
+And of course, your project's build process will impose additional
+requirements on the buildslaves. These hosts must have all the tools
+necessary to compile and test your project's source code.
+
@node Installing the code, Creating a buildmaster, Requirements, Installation
@section Installing the code
@@ -498,21 +507,12 @@
PYTHONPATH=. trial -v buildbot.test
@end example
-This should run up to 109 tests, depending upon what VC tools you have
-installed. On my desktop machine it takes about two minutes to complete.
-Nothing should fail, a few might be skipped. If any of the tests fail, you
-should stop and investigate the cause before continuing the installation
-process, as it will probably be easier to track down the bug early.
-
-If you want to test the VC checkout process, you'll need to install a
-tarball of repositories, available from http://buildbot.sf.net/ . Otherwise
-there are about 8 tests which will be skipped (all with names like testSVN
-and testArchHTTP). If you unpack this tarball in ~/tmp, it will create
-~/tmp/buildbot-test-vc-1, and you can enable the extra tests with:
-
- at example
-PYTHONPATH=. BUILDBOT_TEST_VC=~/tmp trial -v buildbot.test
- at end example
+This should run up to 175 tests, depending upon what VC tools you have
+installed. On my desktop machine it takes about four minutes to
+complete. Nothing should fail, a few might be skipped. If any of the
+tests fail, you should stop and investigate the cause before
+continuing the installation process, as it will probably be easier to
+track down the bug early.
If you cannot or do not wish to install the buildbot into a site-wide
location like @file{/usr} or @file{/usr/local}, you can also install
@@ -567,14 +567,13 @@
placed in the working directory, named @file{master.cfg.sample}, which
can be copied to @file{master.cfg} and edited to suit your purposes.
-Internal details:
-
-This command creates a file named @file{buildbot.tac} that contains
-all the state necessary to create the buildmaster. Twisted has a tool
-called @code{twistd} which can use this .tac file to create and launch
-a buildmaster instance. twistd takes care of logging and daemonization
-(running the program in the background). @file{/usr/bin/buildbot} is a
-front end which runs twistd for you.
+(Internal details: This command creates a file named
+ at file{buildbot.tac} that contains all the state necessary to create
+the buildmaster. Twisted has a tool called @code{twistd} which can use
+this .tac file to create and launch a buildmaster instance. twistd
+takes care of logging and daemonization (running the program in the
+background). @file{/usr/bin/buildbot} is a front end which runs twistd
+for you.)
In addition to @file{buildbot.tac}, a small @file{Makefile.sample} is
installed. This can be used as the basis for customized daemon startup,
@@ -669,7 +668,7 @@
@item
the password assigned to your buildslave
@item
-the hostname and port number of the buildmaster, i.e. example.com:8007
+the hostname and port number of the buildmaster, i.e. buildbot.example.org:8007
@end itemize
@item
@@ -706,9 +705,9 @@
libraries installed, and finally the version of the buildbot code
which is running the buildslave.
-If you run many buildslaves, you may want to create
- at file{~buildslave/info} and share it among all the buildslaves with
-symlinks.
+If you run many buildslaves, you may want to create a single
+ at file{~buildslave/info} file and share it among all the buildslaves
+with symlinks.
@end enumerate
@@ -744,11 +743,6 @@
@@reboot buildbot @var{BASEDIR}
@end example
-There is also experimental support for sysvinit-style
- at file{/etc/init.d/buildbot} startup scripts.
- at file{debian/buildbot.init} and @file{debian/buildbot.default} may be
-useful to look at.
-
It is important to remember that the environment provided to cron jobs
and init scripts can be quite different that your normal runtime.
There may be fewer environment variables specified, and the PATH may
@@ -928,14 +922,14 @@
These source trees come from a Version Control System of some kind.
CVS and Subversion are two popular ones, but the Buildbot supports
-others. All VC systems at footnote{except Darcs, but since the Buildbot
-never changes its local source tree we can ignore the fact that Darcs
-uses a less centralized model} have some notion of an upstream
- at code{repository} which acts as a server, from which clients can
-obtain source trees according to various parameters. The VC repository
-provides source trees of various projects, for different branches, and
-from various points in time. The first thing we have to do is to
-specify which source tree we want to get.
+others. All VC systems have some notion of an upstream
+ at code{repository} which acts as a server at footnote{except Darcs, but
+since the Buildbot never modifies its local source tree we can ignore
+the fact that Darcs uses a less centralized model}, from which clients
+can obtain source trees according to various parameters. The VC
+repository provides source trees of various projects, for different
+branches, and from various points in time. The first thing we have to
+do is to specify which source tree we want to get.
@menu
* Generalizing VC Systems::
@@ -965,7 +959,7 @@
out of various source directories are more complex than we're prepared
to take advantage of here}. The SHA1 revision ID used by Monotone is
also a kind of revision stamp, in that it specifies a unique copy of
-the source tree.
+the source tree, as does a Darcs ``context'' file.
When we aren't intending to make any changes to the sources we check out
(at least not any that need to be committed back upstream), there are two
@@ -1108,13 +1102,13 @@
@heading Who
-Each Change has a @code{who} attribute, which specifies which developer
-is responsible for the change. This is a string which comes from a
-namespace controlled by the VC repository. Frequently this means it is
-a username on the host which runs the repository, but not all VC
-systems require this (Arch, for example, would use a fully-qualified
- at code{Arch ID}, which looks like an email address). Each
-StatusNotifier will map the @code{who} attribute into something
+Each Change has a @code{who} attribute, which specifies which
+developer is responsible for the change. This is a string which comes
+from a namespace controlled by the VC repository. Frequently this
+means it is a username on the host which runs the repository, but not
+all VC systems require this (Arch, for example, uses a fully-qualified
+ at code{Arch ID}, which looks like an email address, as does Darcs).
+Each StatusNotifier will map the @code{who} attribute into something
appropriate for their particular means of communication: an email
address, an IRC handle, etc.
@@ -1153,9 +1147,9 @@
@item SVN
@code{revision} is an int, a transation number (r%d)
@item Darcs
-does not yet use @code{revision}
+ at code{revision} is a large string, the output of @code{darcs changes --context}
@item Arch/Bazaar
- at code{revision} is a string, ending in --patch-%d
+ at code{revision} is the full revision ID (ending in --patch-%d)
@item P4
@code{revision} is an int, the transaction number
@end table
@@ -1172,8 +1166,8 @@
subdirectories of the repository, so the file's ``svnurl'' is a
combination of some base URL, the branch name, and the filename within
the branch. (In a sense, the branch name and the filename inhabit the
-same namespace). For Darcs, the branch name @emph{replaces} the
-repository.
+same namespace). Darcs branches are subdirectories of a base URL just
+like SVN.
@table @samp
@item CVS
@@ -1181,7 +1175,7 @@
@item SVN
branch='branches/trunk', files=['src/foo.c']
@item Darcs
-branch='http://darcs.example.org/repos/trunk', files=['src/foo.c']
+branch='branches/trunk', files=['src/foo.c']
@item Arch/Bazaar
branch='buildbot--usebranches--0', files=['buildbot/master.py']
@end table
@@ -1224,8 +1218,8 @@
The @code{tree-stable-timer} and @code{isFileImportant} decisions are
made by the Scheduler. Dependencies are also implemented here.
-Periodic builds (those which are run every N seconds rather than
-because of new Changes) are triggered by a special @code{Periodic}
+Periodic builds (those which are run every N seconds rather than after
+new Changes arrive) are triggered by a special @code{Periodic}
Scheduler subclass. The default Scheduler class can also be told to
watch for specific branches, ignoring Changes on other branches. This
may be useful if you have a trunk and a few release branches which
@@ -1244,7 +1238,7 @@
@code{Scheduler} instances are activated by placing them in the
@code{c['schedulers']} list in the buildmaster config file. Each
-Scheduler gets a unique name.
+Scheduler has a unique name.
@node BuildSet, BuildRequest, Schedulers, Concepts
@@ -1253,10 +1247,10 @@
@cindex BuildSet
A @code{BuildSet} is the name given to a set of Builds that all
-compile/test the same thing on multiple Builders. In general, all
-these component Builds will perform the same sequence of Steps, using
-the same source code, but on different platforms or against a
-different set of libraries.
+compile/test the same version of the tree on multiple Builders. In
+general, all these component Builds will perform the same sequence of
+Steps, using the same source code, but on different platforms or
+against a different set of libraries.
The @code{BuildSet} is tracked as a single unit, which fails if any of
the component Builds have failed, and therefore can succeed only if
@@ -1297,7 +1291,7 @@
@item (revision=REV, changes=None, patch=(LEVEL, DIFF))
This checks out the tree at the given revision REV, then applies a
-patch (using @code{diff -pLEVEL <DIFF}). The @code{try} feature uses
+patch (using @code{diff -pLEVEL <DIFF}). The @ref{try} feature uses
this kind of @code{SourceStamp}. If @code{patch} is None, the patching
step is bypassed.
@@ -1354,8 +1348,8 @@
the @code{BuildFactory} is the way to specify what happens each time a
build is done.
-Each @code{Builder} is associated with a single @code{BuildSlave}. A
- at code{Builder} which is used to perform OS-X builds (as opposed to
+Each @code{Builder} is associated with one of more @code{BuildSlaves}.
+A @code{Builder} which is used to perform OS-X builds (as opposed to
Linux or Solaris builds) should naturally be associated with an
OS-X-based buildslave.
@@ -1394,7 +1388,7 @@
Each Change has a single User who is responsible for that Change. Most
Builds have a set of Changes: the Build represents the first time these
-Changes have been built and tested by the BuildBot. The build has a
+Changes have been built and tested by the Buildbot. The build has a
``blamelist'' that consists of a simple union of the Users responsible
for all the Build's Changes.
@@ -1414,13 +1408,14 @@
Problem. The Problem lasts until the test case starts passing again, at
which point the Problem is said to be ``resolved''.
-If there appears to be a code change went into the tree at the same time
-as the test started failing, that Change is marked as being resposible for
-the Problem, and the user who made the change is added to the Problem's
-``Guilty'' list. In addition to this user, there may be others who share
-responsibility for the Problem (module owners, sponsoring developers). In
-addition to the Responsible Users, there may be a set of Interested Users,
-who take an interest in the fate of the Problem.
+If there appears to be a code change that went into the tree at the
+same time as the test started failing, that Change is marked as being
+resposible for the Problem, and the user who made the change is added
+to the Problem's ``Guilty'' list. In addition to this user, there may
+be others who share responsibility for the Problem (module owners,
+sponsoring developers). In addition to the Responsible Users, there
+may be a set of Interested Users, who take an interest in the fate of
+the Problem.
Problems therefore have sets of Users who may want to be kept aware of
the condition of the problem as it changes over time. If configured, the
@@ -1512,8 +1507,8 @@
@code{buildbot master} command). This file completely specifies which
Builders are to be run, which slaves they should use, how Changes
should be tracked, and where the status information is to be sent. The
-buildmaster's .tac file names the base directory; everything else
-comes from the config file.
+buildmaster's @file{buildbot.tac} file names the base directory;
+everything else comes from the config file.
A sample config file was installed for you when you created the
buildmaster, but you will need to edit it before your buildbot will do
@@ -1590,9 +1585,9 @@
@table @code
@item basedir
-the base directory for the buildmaster. This string is un-expanded, so
-it might start with a tilde which needs to be expanded before use. The
-config file is located in
+the base directory for the buildmaster. This string has not been
+expanded, so it may start with a tilde. It needs to be expanded before
+use. The config file is located in
@code{os.path.expanduser(os.path.join(basedir, 'master.cfg'))}
@end table
@@ -1681,7 +1676,36 @@
subclass to implement more complicated build scheduling.
The docstring for @code{buildbot.scheduler.Scheduler} is the best
-place to see all the options that can be used.
+place to see all the options that can be used. Type @code{pydoc
+buildbot.scheduler.Scheduler} to see it, or look in
+ at file{buildbot/scheduler.py} directly.
+
+The basic Scheduler takes four arguments:
+
+ at table @code
+ at item name
+Each Scheduler must have a unique name. This is only used in status
+displays.
+
+ at item branch
+This Scheduler will pay attention to a single branch, ignoring Changes
+that occur on other branches. Setting @code{branch} equal to the
+special value of @code{None} means it should only pay attention to the
+default branch. Note that @code{None} is a keyword, not a string, so
+you want to use @code{None} and not @code{"None"}.
+
+ at item treeStableTimer
+The Scheduler will wait for this many seconds before starting the
+build. If new changes are made during this interval, the timer will be
+restarted, so really the build will be started after a change and then
+after this many seconds of inactivity.
+
+ at item builderNames
+When the tree-stable-timer finally expires, builds will be started on
+these Builders. Each Builder gets a unique name: these strings must
+match.
+
+ at end table
@example
from buildbot import scheduler
@@ -1694,16 +1718,13 @@
@end example
In this example, the two ``quick'' builds are triggered 60 seconds
-after the tree has been changed (the tree-stable timer is restarted if
-new changes are made during that time, so the build will be run after
-60 seconds of inactivity). The ``full'' builds do not run quite so
-quickly (they wait 5 minutes), so hopefully if the quick builds fail
-due to a missing file or really simple typo, the developer can
+after the tree has been changed. The ``full'' builds do not run quite
+so quickly (they wait 5 minutes), so hopefully if the quick builds
+fail due to a missing file or really simple typo, the developer can
discover and fix the problem before the full builds are started. Both
-Schedulers only pay attention to the default branch (controlled by the
-``None'' in the argument list): any changes on other branches are
-ignored by these Schedulers. Each Scheduler triggers a different set
-of Builders, referenced by name.
+Schedulers only pay attention to the default branch: any changes on
+other branches are ignored by these Schedulers. Each Scheduler
+triggers a different set of Builders, referenced by name.
The third Scheduler in this example just runs the full solaris build
once per day. (note that this Scheduler only lets you control the time
@@ -1842,10 +1863,12 @@
@item slavenames
If you provide @code{slavenames} instead of @code{slavename}, you can
give a list of buildslaves which are capable of running this Builder.
-If multiple buildslaves are connected for any given Builder, it will
-be able to run multiple builds at the same time (one per slave). This
-can also provide a level of redundancy: in case one slave goes
-offline, the others can still keep the Builder working.
+If multiple buildslaves are available for any given Builder, you will
+have some measure of redundancy: in case one slave goes offline, the
+others can still keep the Builder working. In addition, multiple
+buildslaves will allow multiple simultaneous builds for the same
+Builder, which might be useful if you have a lot of forced or ``try''
+builds taking place.
If you use this feature, it is important to make sure that the
buildslaves are all, in fact, capable of running the given build. The
@@ -1942,7 +1965,9 @@
@code{buildbot.master.Manhole} class, you can telnet into the
buildmaster and get an interactive Python shell, which may be useful
for debugging buildbot internals. It is probably only useful for
-buildbot developers.
+buildbot developers. It exposes full access to the buildmaster's
+account (including the ability to modify and delete files), so it
+should not be enabled with a weak or easily guessable password.
@example
from buildbot.master import Manhole
@@ -2033,11 +2058,12 @@
works by listening on a TCP port for clients. These clients subscribe
to hear about commit notifications.
-The buildmaster has a @code{PBService} client built in. There are two
-versions of it, one for old versions of CVSToys (1.0.9 and earlier)
-which used the @code{oldcred} authentication framework, and one for
-newer versions (1.0.10 and later) which use @code{newcred}. Both are
-classes in the @code{buildbot.changes.freshcvs} package.
+The buildmaster has a CVSToys-compatible @code{PBService} client built
+in. There are two versions of it, one for old versions of CVSToys
+(1.0.9 and earlier) which used the @code{oldcred} authentication
+framework, and one for newer versions (1.0.10 and later) which use
+ at code{newcred}. Both are classes in the
+ at code{buildbot.changes.freshcvs} package.
@code{FreshCVSSourceNewcred} objects are created with the following
parameters:
@@ -2111,12 +2137,15 @@
The last kind of ChangeSource actually listens on a TCP port for
clients to connect and push change notices @emph{into} the
-Buildmaster. This is used by the Subversion notification tool (in
-contrib/svn_buildbot.py), which is run by the SVN server and connects
-to the buildmaster directly. This is also useful for creating new
-kinds of change sources that work on a @code{push} model instead of
-some kind of subscription scheme, for example a script which is run
-out of a .forward file.
+Buildmaster. This is used by the built-in @code{buildbot sendchange}
+notification tool, as well as the VC-specific
+ at file{contrib/svn_buildbot.py} and @file{contrib/arch_buildbot.py}
+tools. These tools are run by the repository (in a commit hook
+script), and connect to the buildmaster directly each time a file is
+comitted. This is also useful for creating new kinds of change sources
+that work on a @code{push} model instead of some kind of subscription
+scheme, for example a script which is run out of an email .forward
+file.
This ChangeSource can be configured to listen on its own TCP port, or
it can share the port that the buildmaster is already using for the
@@ -2146,8 +2175,8 @@
@item @code{user} and @code{passwd}
the user/passwd account information that the client program must use
-to connect. Defaults to @code{change} and @code{changepw}.
- at emph{@code{user} is currently always set to @code{change},
+to connect. Defaults to @code{change} and @code{changepw}. @emph{Not
+Implemented, @code{user} is currently always set to @code{change},
@code{passwd} is always set to @code{changepw}}.
@item @code{prefix}
@@ -2434,7 +2463,7 @@
The @code{SVN} build step performs a
@uref{http://subversion.tigris.org, Subversion} checkout or update.
There are two basic ways of setting up the checkout step, depending
-upon whether you are using branches or not.
+upon whether you are using multiple branches or not.
If all of your builds use the same branch, then you should create the
@code{SVN} step with the @code{svnurl} argument:
@@ -2534,10 +2563,10 @@
from buildbot.process.factory import s
c['sources'] = [PBChangeSource()]
-s = AnyBranchScheduler('main',
- ['trunk', 'features/newthing', 'features/otherthing'],
- 10*60, ['test-i386', 'test-ppc'])
-c['schedulers'] = [s]
+s1 = AnyBranchScheduler('main',
+ ['trunk', 'features/newthing', 'features/otherthing'],
+ 10*60, ['test-i386', 'test-ppc'])
+c['schedulers'] = [s1]
source = s(step.SVN, mode='update',
baseURL='svn://svn.example.org/MyProject/',
defaultBranch='trunk')
@@ -2596,10 +2625,10 @@
slash.
@item defaultBranch
-(allowed only if @code{baseURL} is provided): this specifies the name
-of the branch to use when a Build does not provide one of its own.
-This will be appended to @code{baseURL} to create the string that will
-be passed to the @code{darcs get} command.
+(allowed if and only if @code{baseURL} is provided): this specifies
+the name of the branch to use when a Build does not provide one of its
+own. This will be appended to @code{baseURL} to create the string that
+will be passed to the @code{darcs get} command.
@end table
@@ -2688,7 +2717,7 @@
itself (a class-level attribute of the BuildFactory, defaults to
``@file{build}'').
- at code{ShellCommand} Arguments:
+ at code{ShellCommand} arguments:
@table @code
@item command
@@ -2835,11 +2864,11 @@
f23 = factory.Trial(source, trialpython=["python2.3"])
f24 = factory.Trial(source, trialpython=["python2.4"])
b1 = @{'name': 'p22', 'slavename': 'bot-1, builddir='p22', 'factory': f22,
- 'locks': [slow_lock] @}
+ 'locks': [slow_lock] @}
b2 = @{'name': 'p23', 'slavename': 'bot-1, builddir='p23', 'factory': f23,
- 'locks': [slow_lock] @}
+ 'locks': [slow_lock] @}
b3 = @{'name': 'p24', 'slavename': 'bot-1, builddir='p24', 'factory': f24,
- 'locks': [slow_lock] @}
+ 'locks': [slow_lock] @}
c['builders'] = [b1, b2, b3]
@end example
@@ -2872,13 +2901,13 @@
]
fast_factory = factory.BuildFactory(fast_steps)
b1 = @{'name': 'full1', 'slavename': 'bot-slow, builddir='full1',
- 'factory': slow_factory@}
+ 'factory': slow_factory@}
b2 = @{'name': 'full2', 'slavename': 'bot-slow, builddir='full2',
- 'factory': slow_factory@}
+ 'factory': slow_factory@}
b3 = @{'name': 'full3', 'slavename': 'bot-fast, builddir='full3',
- 'factory': fast_factory@}
+ 'factory': fast_factory@}
b4 = @{'name': 'full4', 'slavename': 'bot-fast, builddir='full4',
- 'factory': fast_factory@}
+ 'factory': fast_factory@}
c['builders'] = [b1, b2, b3, b4]
@end example
@@ -3040,16 +3069,11 @@
@node BuildFactory Attributes, Quick builds, BuildFactory, BuildFactory
@subsubsection BuildFactory Attributes
-Several attributes from the BuildFactory are copied into each Build.
+Some attributes from the BuildFactory are copied into each Build.
@cindex treeStableTimer
@table @code
- at item treeStableTimer
-provides the duration of the ``tree-stable timer'', in seconds. Builds
-will wait until the tree has been seen no important changes for at
-least this long.
-
@item useProgress
(defaults to True): if True, the buildmaster keeps track of how long
each step takes, so it can provide estimates of how long future builds
@@ -3414,7 +3438,11 @@
service.MultiService which will be attached to the BuildMaster object
when the configuration is processed. They should use
@code{self.parent.getStatus()} to get access to the top-level IStatus
-object.)
+object, either inside @code{startService} or later. They may call
+ at code{status.subscribe()} in @code{startService} to receive
+notifications of builder events, in which case they must define
+ at code{builderAdded} and related methods. See the docstrings in
+ at file{buildbot/interfaces.py} for full details.)
@menu
* HTML Waterfall::
@@ -3454,10 +3482,10 @@
such a system, it is convenient to create a dedicated @code{buildbot}
user, then set @code{distrib_port} to
@code{os.path.expanduser("~/.twistd-web-pb")}. This configuration will
-make the HTML status page available at @code{http://host/~buildbot/}.
+make the HTML status page available at @code{http://host/~buildbot/} .
Suitable URL remapping can make it appear at
@code{http://host/buildbot/}, and the right virtual host setup can
-even place it at @code{http://buildbot.host/}.
+even place it at @code{http://buildbot.host/} .
@node IRC Bot, PBListener, HTML Waterfall, Status Delivery
@subsection IRC Bot
@@ -3744,7 +3772,7 @@
performed inside the buildmaster's config file. The disadvantages are
that it is less secure (while the ``cred'' authentication system does
not expose the password in plaintext over the wire, it does not offer
-most of the other security properties that SSH does. In addition, the
+most of the other security properties that SSH does). In addition, the
buildmaster admin is responsible for maintaining the username/password
list, adding and deleting entries as developers come and go.
@@ -3755,8 +3783,10 @@
command queue directory of @file{MASTERDIR/jobdir} (and assuming that
all your project developers were members of the @code{developers} unix
group), you would first create that directory (with @command{mkdir
-MASTERDIR/jobdir; chgrp developers MASTERDIR/jobdir; chmod g+rwx,o-rwx
-MASTERDIR/jobdir}), and then use the following scheduler in the
+MASTERDIR/jobdir MASTERDIR/jobdir/new MASTERDIR/jobdir/cur
+MASTERDIR/jobdir/tmp; chgrp developers MASTERDIR/jobdir
+MASTERDIR/jobdir/*; chmod g+rwx,o-rwx MASTERDIR/jobdir
+MASTERDIR/jobdir/*}), and then use the following scheduler in the
buildmaster's config file:
@example
@@ -3778,7 +3808,8 @@
@code{builderNames} argument as the @code{Try_Jobdir} form, but
accepts an addtional @code{port} argument (to specify the TCP port to
listen on) and a @code{userpass} list of username/password pairs to
-accept:
+accept. Remember to use good passwords for this: the security of the
+buildslave accounts depends upon it:
@example
from buildbot.scheduler import Try_Userpass
@@ -3983,6 +4014,11 @@
@code{Change} that gets submitted:
@table @code
+ at item --branch
+This provides the (string) branch specifier. If omitted, it defaults
+to None, indicating the ``default branch''. All files included in this
+Change must be on the same branch.
+
@item --revision_number
This provides a (numeric) revision number for the change, used for VC systems
that use numeric transaction numbers (like Subversion).
@@ -4136,6 +4172,10 @@
@node Developer's Appendix, Index, Resources, Top
@unnumbered Developer's Appendix
+This appendix contains random notes about the implementation of the
+Buildbot, and is likely to only be of use to people intending to
+extend the Buildbot's internals.
+
The buildmaster consists of a tree of Service objects, which is shaped
as follows:
More information about the Commits
mailing list