# 2.5.11. Build Sets

A `BuildSet` represents a set of `Build`s that all compile and/or test the same version of the source tree. Usually, these builds are created by multiple `Builder`s and will thus execute different steps.

The `BuildSet` is tracked as a single unit, which fails if any of the component `Build`s have failed, and therefore can succeed only if all of the component `Build`s have succeeded. There are two kinds of status notification messages that can be emitted for a `BuildSet`: the `firstFailure` type (which fires as soon as we know the `BuildSet` will fail), and the `Finished` type (which fires once the `BuildSet` has completely finished, regardless of whether the overall set passed or failed).

A `BuildSet` is created with a set of one or more source stamp tuples of `(branch, revision, changes, patch)`, some of which may be `None`, and a list of `Builder`s on which it is to be run. They are then given to the BuildMaster, which is responsible for creating a separate `BuildRequest` for each `Builder`.

There are a couple of different likely values for the `SourceStamp`:

`(revision=None, changes=CHANGES, patch=None)`

  This is a `SourceStamp` used when a series of `Change`s have triggered a build. The VC step will attempt to check out a tree that contains CHANGES (and any changes that occurred before CHANGES, but not any that occurred after them.)

`(revision=None, changes=None, patch=None)`

  This builds the most recent code on the default branch. This is the sort of `SourceStamp` that would be used on a `Build` that was triggered by a user request, or a `Periodic` scheduler. It is also possible to configure the VC Source Step to always check out the latest sources rather than paying attention to the `Change`s in the `SourceStamp`, which will result in the same behavior as this.

`(branch=BRANCH, revision=None, changes=None, patch=None)`

  This builds the most recent code on the given BRANCH. Again, this is generally triggered by a user request or a `Periodic` scheduler.

`(revision=REV, changes=None, patch=(LEVEL, DIFF, SUBDIR_ROOT))`

  This checks out the tree at the given revision REV, then applies a patch (using `patch -pLEVEL <DIFF`) from inside the relative directory SUBDIR_ROOT. Item SUBDIR_ROOT is optional and defaults to the builder working directory. The `try` command creates this kind of `SourceStamp`. If `patch` is `None`, the patching step is bypassed.

The buildmaster is responsible for turning the `BuildSet` into a set of `BuildRequest` objects and queueing them on the appropriate `Builder`s.