[Buildbot-commits] buildbot/docs buildbot.texinfo,1.44,1.45
Brian Warner
warner at users.sourceforge.net
Mon Apr 24 06:45:39 UTC 2006
Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv25669/docs
Modified Files:
buildbot.texinfo
Log Message:
Revision: arch at buildbot.sf.net--2004/buildbot--dev--0--patch-506
Creator: Brian Warner <warner at lothar.com>
add 'build properties', update test_vc
2006-04-23 Brian Warner <warner at lothar.com>
* buildbot/test/test_vc.py (VCBase.checkGotRevision): test
'got_revision' build property for all VC systems that implement
accurate ones: SVN, Darcs, Arch, Bazaar, Mercurial.
* buildbot/slave/commands.py (SourceBase._handleGotRevision): try
to determine which revision we actually obtained
(CVS.parseGotRevision): implement this for CVS, which just means
to grab a timestamp. Not ideal, and it depends upon the buildslave
having a clock that is reasonably well syncronized with the server,
but it's better than nothing.
(SVN.parseGotRevision): implement it for SVN, which is accurate
(Darcs.parseGotRevision): same
(Arch.parseGotRevision): same
(Bazaar.parseGotRevision): same
(Mercurial.parseGotRevision): same
* buildbot/process/step.py (LoggedRemoteCommand.remoteUpdate):
keep a record of all non-stdout/stderr/header/rc status updates,
for the benefit of RemoteCommands that send other useful things,
like got_revision
(Source.commandComplete): put any 'got_revision' status values
into a build property of the same name
* buildbot/process/step_twisted.py (Trial): update to deal with
new ShellCommand refactoring
* docs/buildbot.texinfo (Build Properties): document new feature
that allows BuildSteps to get/set Build-wide properties like which
revision was requested and/or checked out.
* buildbot/interfaces.py (IBuildStatus.getProperty): new method
* buildbot/status/builder.py (BuildStatus.getProperty): implement
it. Note that this bumps the persistenceVersion of the saved Build
object, so add the necessary upgrade-old-version logic to include
an empty properties dict.
* buildbot/process/base.py (Build.setProperty): implement it
(Build.getProperty): same
(Build.startBuild): change build startup to set 'branch',
'revision', and 'slavename' properties at the right time
* buildbot/process/step.py (BuildStep.__init__): change setup to
require 'build' argument in a better way
(LoggingBuildStep): split ShellCommand into two pieces, for better
subclassing elsewhere. LoggingBuildStep is a BuildStep which runs
a single RemoteCommand that sends stdout/stderr status text. It
also provides the usual commandComplete / createSummary /
evaluateCommand / getText methods to be overridden...
(ShellCommand): .. whereas ShellCommand is specifically for
running RemoteShellCommands. Other shell-like BuildSteps (like
Source) can inherit from LoggingBuildStep instead of ShellCommand
(WithProperties): marker class to do build-property interpolation
(Source): inherit from LoggingBuildStep instead of ShellCommand
(RemoteDummy): same
* buildbot/test/test_properties.py: test new functionality
2006-04-21 Brian Warner <warner at lothar.com>
* buildbot/test/test_vc.py: rename testBranch to
testCheckoutBranch to keep the tests in about the right
alphabetical order
Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -d -r1.44 -r1.45
--- buildbot.texinfo 18 Apr 2006 07:47:58 -0000 1.44
+++ buildbot.texinfo 24 Apr 2006 06:45:37 -0000 1.45
@@ -157,6 +157,8 @@
* Configure::
* Compile::
* Test::
+* Writing New BuildSteps::
+* Build Properties::
Build Factories
@@ -3013,6 +3015,8 @@
* Configure::
* Compile::
* Test::
+* Writing New BuildSteps::
+* Build Properties::
@end menu
@node Configure, Compile, Simple ShellCommand Subclasses, Simple ShellCommand Subclasses
@@ -3032,12 +3036,171 @@
created with any problems that were seen (TODO: the summary is not yet
created).
- at node Test, , Compile, Simple ShellCommand Subclasses
+ at node Test, Writing New BuildSteps, Compile, Simple ShellCommand Subclasses
@subsubsection Test
This is meant to handle unit tests. The default command is @code{make
test}, and the @code{warnOnFailure} flag is set.
+
+
+
+
+ at node Writing New BuildSteps, Build Properties, Test, Simple ShellCommand Subclasses
+ at subsubsection Writing New BuildSteps
+
+While it is a good idea to keep your build process self-contained in
+the source code tree, sometimes it is convenient to put more
+intelligence into your Buildbot configuration. One was to do this is
+to write a custom BuildStep. Once written, this Step can be used in
+the @file{master.cfg} file.
+
+The best reason for writing a custom BuildStep is to better parse the
+results of the command being run. For example, a BuildStep that knows
+about JUnit could look at the logfiles to determine which tests had
+been run, how many passed and how many failed, and then report more
+detailed information than a simple @code{rc==0} -based ``good/bad''
+decision.
+
+TODO: add more description of BuildSteps.
+
+
+ at node Build Properties, , Writing New BuildSteps, Simple ShellCommand Subclasses
+ at subsubsection Build Properties
+
+ at cindex build properties
+
+Each build has a set of ``Build Properties'', which can be used by its
+BuildStep to modify their actions. For example, the SVN revision
+number of the source code being built is available as a build
+property, and a ShellCommand step could incorporate this number into a
+command which create a numbered release tarball.
+
+Some build properties are set when the build starts, such as the
+SourceStamp information. Other properties can be set by BuildSteps as
+they run, for example the various Source steps will set the
+ at code{got_revision} property to the source revision that was actually
+checked out (which can be useful when the SourceStamp in use merely
+requested the ``latest revision'': @code{got_revision} will tell you
+what was actually built).
+
+In custom BuildSteps, you can get and set the build properties with
+the @code{getProperty}/@code{setProperty} methods. Each takes a string
+for the name of the property, and returns or accepts an
+arbitrary at footnote{Build properties are serialized along with the
+build results, so they must be serializable. For this reason, the
+value of any build property should be simple inert data: strings,
+numbers, lists, tuples, and dictionaries. They should not include
+class instances.} object. For example:
+
+ at example
+class MakeTarball(step.ShellCommand):
+ def start(self):
+ self.setCommand(["tar", "czf",
+ "build-%s.tar.gz" % self.getProperty("revision"),
+ "source"])
+ step.ShellCommand.start(self)
+ at end example
+
+ at cindex WithProperties
+
+You can use build properties in ShellCommands by using the
+ at code{WithProperties} wrapper when setting the arguments of the
+ShellCommand. This interpolates the named build properties into the
+generated shell command.
+
+ at example
+from buildbot.process.step import ShellCommand, WithProperties
+
+s(ShellCommand,
+ command=["tar", "czf",
+ WithProperties("build-%s.tar.gz", "revision"),
+ "source"],
+ )
+ at end example
+
+If this BuildStep were used in a tree obtained from Subversion, it
+would create a tarball with a name like @file{build-1234.tar.gz}.
+
+The @code{WithProperties} function does @code{printf}-style string
+interpolation, using strings obtained by calling
+ at code{build.getProperty(propname)}. You can also use python
+dictionary-style string interpolation by using the @code{%(propname)s}
+syntax:
+
+ at example
+s(ShellCommand,
+ command=["tar", "czf",
+ WithProperties("build-%(revision)s.tar.gz"),
+ "source"],
+ )
+ at end example
+
+Note that, like python, you can either do positional-argument
+interpolation @emph{or} keyword-argument interpolation, not both. Thus
+you cannot use a string like
+ at code{WithProperties("foo-%(revision)s-%s", "branch")}.
+
+At the moment, the only way to set build properties is by writing a
+custom BuildStep.
+
+ at heading Common Build Properties
+
+The following build properties are set when the build is started, and
+are available to all steps.
+
+ at table @code
+ at item branch
+
+This comes from the build's SourceStamp, and describes which branch is
+being checked out. This will be @code{None} (which interpolates into
+ at code{WithProperties} as an empty string) if the build is on the
+default branch, which is generally the trunk. Otherwise it will be a
+string like ``branches/beta1.4''. The exact syntax depends upon the VC
+system being used.
+
+ at item revision
+
+This also comes from the SourceStamp, and is the revision of the
+source code tree that was requested from the VC system. When a build
+is requested of a specific revision (as is generally the case when the
+build is triggered by Changes), this will contain the revision
+specification. The syntax depends upon the VC system in use: for SVN
+it is an integer, for Mercurial it is a short string, for Darcs it is
+a rather large string, etc.
+
+If the ``force build'' button was pressed, the revision will be
+ at code{None}, which means to use the most recent revision available.
+This is a ``trunk build''. This will be interpolated as an empty
+string.
+
+ at item got_revision
+
+This is set when a Source step checks out the source tree, and
+provides the revision that was actually obtained from the VC system.
+In general this should be the same as @code{revision}, except for
+trunk builds, where @code{got_revision} indicates what revision was
+current when the checkout was performed. This can be used to rebuild
+the same source code later.
+
+Note that for some VC systems (Darcs in particular), the revision is a
+large string containing newlines, and is not suitable for
+interpolation into a filename.
+
+ at item slavename
+
+This is a string which identifies which buildslave the build is
+running on.
+
+ at item buildnumber
+
+Each build gets a number, scoped to the Builder (so the first build
+performed on any given Builder will have a build number of 0). This
+integer property contains the build's number.
+
+ at end table
+
+
@node Interlocks, Build Factories, Build Steps, Build Process
@section Interlocks
More information about the Commits
mailing list