[Buildbot-commits] buildbot/docs buildbot.texinfo,1.132,1.133

[Brian Warner]

Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv30892/docs

Modified Files:
	buildbot.texinfo 
Log Message:
[project @ #56:trigger.patch]
Schedulers that can be triggered by buildsteps, allowing more
fine-grained control than Dependent schedulers.

Original author: dustin at v.igoro.us
Date: 2008-02-17 04:49:06+00:00

Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.132
retrieving revision 1.133
diff -u -d -r1.132 -r1.133
--- buildbot.texinfo	18 Mar 2008 20:36:14 -0000	1.132
+++ buildbot.texinfo	20 Mar 2008 17:43:09 -0000	1.133
@@ -2192,6 +2192,12 @@
 scheduler is triggered. The next section (@pxref{Build Dependencies})
 describes this scheduler in more detail.
 
+ at item Triggerable
+This scheduler does nothing until it is triggered by a Trigger
+step in another build.  This facilitates a more general form of
+build dependencies, as described in the next section (@pxref{Build
+Dependencies}).
+
 @item Periodic
 This simple scheduler just triggers a build every N seconds.
 
@@ -2218,6 +2224,7 @@
 @cindex Dependent
 @cindex Dependencies
 @slindex buildbot.scheduler.Dependent
+ at slindex buildbot.scheduler.Triggerable
 
 It is common to wind up with one kind of build which should only be
 performed if the same source code was successfully handled by some
@@ -2260,6 +2267,55 @@
 @code{Scheduler} @emph{instance}, not a name. This makes it impossible
 to create circular dependencies in the config file.
 
+A more general way to coordinate builds is by ``triggering'' schedulers
+from builds.  The Triggerable waits to be triggered by a
+Trigger step in another build.  That step can optionally
+wait for the scheduler's builds to complete.  This provides two
+advantages over Dependent schedulers.  First, the same scheduler
+can be triggered from multiple builds.  Second, the ability to wait
+for a Triggerable's builds to complete provides a form of
+"subroutine call", where one or more builds can "call" a scheduler
+to perform some work for them,  perhaps on other buildslaves.
+
+ at example
+from buildbot import scheduler
+from buildbot.steps import trigger
+checkin = scheduler.Scheduler("checkin", None, 5*60,
+                            ["checkin"])
+nightly = scheduler.Scheduler("nightly", ...
+                            ["nightly"])
+mktarball = scheduler.Triggerable("mktarball",
+                              ["mktarball"])
+build = scheduler.Triggerable("build-all-platforms",
+                              ["build-all-platforms"])
+test = scheduler.Triggerable("distributed-test",
+                              ["distributed-test"])
+package = scheduler.Triggerable("package-all-platforms",
+                              ["package-all-platforms"])
+c['schedulers'] = [checkin, nightly, build, test, package]
+
+checkin_factory = factory.BuildFactory()
+f.addStep(trigger.TriggerStep('mktarball',
+    schedulers=['mktarball'],
+    waitForFinish=1)
+f.addStep(trigger.TriggerStep('build',
+    schedulers=['build-all-platforms'],
+    waitForFinish=1)
+f.addStep(trigger.TriggerStep('test',
+    schedulers=['distributed-test'],
+    waitForFinish=1)
+
+nightly_factory = factory.BuildFactory()
+f.addStep(trigger.TriggerStep('mktarball',
+    schedulers=['mktarball'],
+    waitForFinish=1)
+f.addStep(trigger.TriggerStep('build',
+    schedulers=['build-all-platforms'],
+    waitForFinish=1)
+f.addStep(trigger.TriggerStep('package',
+    schedulers=['package-all-platforms'],
+    waitForFinish=1)
+ at end example
 
 @node Setting the slaveport, Buildslave Specifiers, Listing Change Sources and Schedulers, Configuration
 @section Setting the slaveport
@@ -3666,6 +3722,7 @@
 * Simple ShellCommand Subclasses::  
 * Python BuildSteps::           
 * Transferring Files::          
+* Triggering Schedulers::
 * Writing New BuildSteps::      
 @end menu
 
@@ -4602,7 +4659,7 @@
 
 @end table
 
- at node Python BuildSteps, Transferring Files, Simple ShellCommand Subclasses, Build Steps
+ at node Python BuildSteps, Triggering Schedulers, Simple ShellCommand Subclasses, Build Steps
 @subsection Python BuildSteps
 
 Here are some BuildSteps that are specifcally useful for projects
@@ -4678,7 +4735,7 @@
 @end example
 
 
- at node Transferring Files, Writing New BuildSteps, Python BuildSteps, Build Steps
+ at node Transferring Files, Triggering Schedulers, Python BuildSteps, Build Steps
 @subsection Transferring Files
 
 @cindex File Transfer
@@ -4767,7 +4824,39 @@
 creation time (@pxref{Buildslave Options}).
 
 
- at node Writing New BuildSteps,  , Transferring Files, Build Steps
+ at node Triggering Schedulers, Writing New BuildSteps, Transferring Files, Build Steps
+ at subsection Triggering Schedulers
+
+The counterpart to the Triggerable described in section
+ at pxref{Build Dependencies} is the Trigger BuildStep.
+
+ at example
+from buildbot.steps.trigger import Trigger
+f.addStep(Trigger,
+          schedulers=['build-prep'],
+          waitForFinish=1,
+          updateSourceStamp=1)
+ at end example
+
+The @code{schedulers=} argument lists the Triggerables
+that should be triggered when this step is executed.  Note that
+it is possible, but not advisable, to create a cycle where a build
+continually triggers itself, because the schedulers are specified
+by name.
+
+If @code{waitForFinish} is true, then the step will not finish until
+all of the builds from the triggered schedulers have finished.  If this
+argument is not given, then the buildstep succeeds immediately after
+triggering the schedulers.
+
+If @code{updateSourceStamp} is true, then step updates the SourceStamp
+given to the Triggerables to include @code{got_revision}
+(the revision actually used in this build) as @code{revision} (the
+revision to use in the triggered builds).  This is useful to ensure
+that all of the builds use exactly the same SourceStamp, even if
+other Changes have occurred while the build was running.
+
+ at node Writing New BuildSteps,  , Triggering Schedulers, Build Steps
 @subsection Writing New BuildSteps
 
 While it is a good idea to keep your build process self-contained in