3.10.3. BuildFactory

3.10.3.1. BuildFactory Implementation Note

The default BuildFactory, provided in the buildbot.process.factory module, contains an internal list of BuildStep factories. A BuildStep factory is simply a callable that produces a new BuildStep with the same arguments that were used during its construction. These BuildStep factories are constructed when the config file is read, by asking the instances passed to addStep for their factories.

When asked to create a Build, the BuildFactory puts a copy of the list of BuildStep factories into the new Build object. When the Build is actually started, these BuildStep factories are used to create the actual set of BuildSteps, which are then executed one at a time. This serves to give each Build an independent copy of each step.

Each step can affect the build process in the following ways:

• If the step’s haltOnFailure attribute is True, then a failure in the step (i.e. if it completes with a result of FAILURE) will cause the whole build to be terminated immediately: no further steps will be executed, with the exception of steps with alwaysRun set to True. haltOnFailure is useful for setup steps upon which the rest of the build depends: if the Git checkout or ./configure process fails, there is no point in trying to compile or test the resulting tree.

• If the step’s alwaysRun attribute is True, then it will always be run, regardless of if previous steps have failed. This is useful for cleanup steps that should always be run to return the build directory or worker into a good state.

• If the flunkOnFailure or flunkOnWarnings flag is set, then a result of FAILURE or WARNINGS will mark the build as a whole as FAILED. However, the remaining steps will still be executed. This is appropriate for things like multiple testing steps: a failure in any one of them will indicate that the build has failed, however it is still useful to run them all to completion.

• Similarly, if the warnOnFailure or warnOnWarnings flag is set, then a result of FAILURE or WARNINGS will mark the build as having WARNINGS, and the remaining steps will still be executed. This may be appropriate for certain kinds of optional build or test steps. For example, a failure experienced while building documentation files should be made visible with a WARNINGS result but not be serious enough to warrant marking the whole build with a FAILURE.

In addition, each Step produces its own results, may create logfiles, etc. However only the flags described above have any effect on the build as a whole.

The pre-defined BuildSteps like Git and Compile have reasonably appropriate flags set on them already. For example, without a source tree there is no point in continuing a build, so the Git class has the haltOnFailure flag set to True. Look in buildbot/steps/*.py to see how the other Steps are marked.

Each Step is created with an additional workdir argument that indicates where its actions should take place. This is specified as a subdirectory of the worker’s base directory, with a default value of build. This is only implemented as a step argument (as opposed to simply being a part of the base directory) because the Git/SVN steps need to perform their checkouts from the parent directory.