Here is an example using several different features of CC:
<modificationset quietperiod="300">
<cvs
cvsroot=":pserver:userid@computername.domain:/src/CVS"
tag="ursa_1_1"/>
</modificationset>
<schedule interval="1800" >
<ant buildfile="cruise_build.xml"
target="gate.test.build"
time="2330" />
<ant buildfile="cruise_build.xml"
target="gate.master.build"
multiple="1"/>
</schedule>
The first thing to notice is the the modificationset and scheduling mechanisms are separate from each other. The quietperiod is only used in whatever sourcecontrol you use (in this case cvs) to determine if it should wait longer before trying to run the build.
Basically, when the cvs source control returns its set of modifications, cruisecontrol checks the timestamps to determine when each of them was committed. If any of the modifications were committed within the quietperiod (in this case, within the last 300 seconds), it will wait longer and retry the modificationset sometime later. (Refer to the ModificationSetCodeSample for the logic.) After the remainder of the quietperiod has passed, CC awakens and looks again for modifications. If modifications were detected, a new quietperiod begins. If no modifications were detected in the quietperiod timeframe, cc can go ahead and start the build.
Now, the scheduling is totally separate from the above. First of all, CC uses the interval to decide when to wake up and check the modificationset...nothing else determines this: only the interval. So in this example, every 1800 seconds CC wakes up and runs the modificationset (which is everything described above, including the testing of the quietperiod). If the modification set returns modifications, CC then tries to find a valid builder. In this case both candidates are ant builders, but they differ in that one is sensitive to a time (a "time" builder), and the other is sensitive to a given number (or "multiple") of build loop iterations. CC first tries the "time" builder since it is listed first. The use of the time builder depends on the time of the last build, the current time, and the time defined by the builder, as follows:
If the time of the last build is less than the current time, and the builder time is less than the current time, and you are building on a valid day according to the day attribute, the time builder will be selected. (Refer to the TimeBuilderCodeSample for the logic.)
Note: time is totally generic, and has no reference to date/day. For example, 0830 tomorrow, 0830 today and 0830 yesterday are all less than 1130 today.
In terms of our example, if the build runs (i.e. there are modifications) at 0925 or 2125 or any other time less than 2330, then the time builder will not be selected. It then moves onto the "multiple" ant builder and because the multiple is 1, it will always be selected as the default. The build will run and complete (hopefully) and the last successful build time is set. Then, everything starts over again...the interval decides when to wake up, the modificationset is checked, if modifications, then the builder is selected, the build runs, the build finishes, the interval decides when to wake up...and on and on forever.
As a side note, there are many instances when the ant time builder selection algorithm breaks down. Please search the cc-user mailing list for more detailed discussions.
>>CC first tries the "time" builder since it is listed first.
The config ref (http://cruisecontrol.sourceforge.net/main/configxml.html#schedule) says: "Builds using the time attribute take precedence over builds using the multiple attribute." If true, then the time-based builder is, in fact, tried first but not because it's first in the list. It's tried first because it's the only time-based builder.
I was still confused about some aspects of time vs. multiple builder after reading this page. After some thought I have come to realize the following that don't seem to be very clearly stated anywere: 1) Each builder is either time-based or multiple-based (there are no other flavors). 2) If there is no time param, then it's multiple-based (multiple=1).
To make this more helpful, I'd say either remove the multiple param from the 2nd builder since its presence is confusing or add a 3rd builder in the 2nd position with multiple>1. For example, set multiple to 2 in the new builder so that every other build alternates between the 2nd and 3rd builder ... if the 1st (time-based) builder is not selected.