A BuildFactory defines the steps that every build will follow. Think of it as
a glorified script. For example, a build which consists of a CVS checkout
followed by a make build
would be constructed as follows:
from buildbot.steps import source, shell from buildbot.process import factory f = factory.BuildFactory() f.addStep(source.CVS(cvsroot=CVSROOT, cvsmodule="project", mode="update")) f.addStep(shell.Compile(command=["make", "build"]))
It is also possible to pass a list of steps into the
BuildFactory
when it is created. Using addStep
is
usually simpler, but there are cases where is is more convenient to
create the list of steps ahead of time, perhaps using some Python
tricks to generate the steps.
from buildbot.steps import source, shell from buildbot.process import factory all_steps = [ source.CVS(cvsroot=CVSROOT, cvsmodule="project", mode="update"), shell.Compile(command=["make", "build"]), ] f = factory.BuildFactory(all_steps)
Finally, you can also add a sequence of steps all at once:
f.addSteps(all_steps)
useProgress
workdir
# # pre-repository working directory # def workdir (source_stamp): return hashlib.md5 (source_stamp.repository).hexdigest ()[:8] build = factory.BuildFactory() build.workdir = workdir build.addStep (Git (mode = "update")) ... builders.append ({'name': 'mybuilder', 'slavename': 'myslave', 'builddir': 'mybuilder', 'factory': build}) # You'll end up with workdirs like: # # Repo1 => <buildslave-base>/mybuilder/a78890ba # Repo2 => <buildslave-base>/mybuilder/0823ba88 # ...
You could make the workdir() function compute other paths, based on parts of the repo URL in the sourcestamp, or lookup in a lookup table based on repo URL. As long as there is a permanent 1:1 mapping between repos and workdir this will work.
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-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 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:
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 CVS checkout or ./configure
process fails, there is no point in trying to compile or test the
resulting tree.
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 build slave into a good state.
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.
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 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 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 slave builder'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.