3.5.3. BuildFactory¶
3.5.3.1. BuildFactory Implementation Note¶
The default BuildFactory
, provided in the buildbot.process.factory
module, contains an internal list of BuildStep specifications: a list of (step_class, kwargs)
tuples for each.
These specification tuples are constructed when the config file is read, by asking the instances passed to addStep
for their subclass and arguments.
To support config files from Buildbot version 0.7.5 and earlier, addStep
also accepts the f.addStep(shell.Compile, command=["make","build"])
form, although its use is discouraged because then the Compile
step doesn’t get to validate or complain about its arguments until build time.
The modern pass-by-instance approach allows this validation to occur while the config file is being loaded, where the admin has a better chance of noticing problems.
When asked to create a Build
, the BuildFactory
puts a copy of the list of step specifications into the new Build
object.
When the Build
is actually started, these step specifications are used to create the actual set of BuildStep
s, 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 isTrue
, then a failure in the step (i.e. if it completes with a result ofFAILURE
) will cause the whole build to be terminated immediately: no further steps will be executed, with the exception of steps withalwaysRun
set toTrue
.haltOnFailure
is useful for setup steps upon which the rest of the build depends: if the CVS checkout or ./configure process fails, there is no point in trying to compile or test the resulting tree. - If the step’s
alwaysRun
attribute isTrue
, 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
orflunkOnWarnings
flag is set, then a result ofFAILURE
orWARNINGS
will mark the build as a whole asFAILED
. 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
orwarnOnWarnings
flag is set, then a result ofFAILURE
orWARNINGS
will mark the build as havingWARNINGS
, 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 aWARNINGS
result but not be serious enough to warrant marking the whole build with aFAILURE
.
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 BuildStep
s like CVS
and Compile
have reasonably appropriate flags set on them already.
For example, without a source tree there is no point in continuing the build, so the CVS
class has the haltOnFailure
flag set to True
.
Look in buildbot/steps/*.py
to see how the other Step
s 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 CVS/SVN steps need to perform their checkouts from the parent directory.