4.11.2.1 WithProperties

You can use build properties in ShellCommands by using the WithProperties wrapper when setting the arguments of the ShellCommand. This interpolates the named build properties into the generated shell command. Most step parameters accept WithProperties. Please file bugs for any parameters which do not.

     from buildbot.steps.shell import ShellCommand
     from buildbot.process.properties import WithProperties
     
     f.addStep(ShellCommand(
               command=["tar", "czf",
                        WithProperties("build-%s.tar.gz", "revision"),
                        "source"]))

If this BuildStep were used in a tree obtained from Subversion, it would create a tarball with a name like build-1234.tar.gz.

The WithProperties function does printf-style string interpolation, using strings obtained by calling build.getProperty(propname). Note that for every %s (or %d, etc), you must have exactly one additional argument to indicate which build property you want to insert.

You can also use python dictionary-style string interpolation by using the %(propname)s syntax. In this form, the property name goes in the parentheses, and WithProperties takes no additional arguments:

     f.addStep(ShellCommand(
               command=["tar", "czf",
                        WithProperties("build-%(revision)s.tar.gz"),
                        "source"]))

Don't forget the extra “s” after the closing parenthesis! This is the cause of many confusing errors.

The dictionary-style interpolation supports a number of more advanced syntaxes, too.

propname:-replacement

If propname exists, substitute its value; otherwise, substitute replacement. replacement may be empty (%(propname:-)s)

propname:+replacement

If propname exists, substitute replacement; otherwise, substitute an empty string.

Although these are similar to shell substitutions, no other substitutions are currently supported, and replacement in the above cannot contain more substitutions.

Note: like python, you can either do positional-argument interpolation or keyword-argument interpolation, not both. Thus you cannot use a string like WithProperties("foo-%(revision)s-%s", "branch").

Common Build Properties

The following build properties are set when the build is started, and are available to all steps.

branch

This comes from the build's SourceStamp, and describes which branch is being checked out. This will be None (which interpolates into 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.

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. This is always a string, although 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 None, which means to use the most recent revision available. This is a “trunk build”. This will be interpolated as an empty string.

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 revision, except for trunk builds, where 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.

buildername

This is a string that indicates which Builder the build was a part of. The combination of buildername and buildnumber uniquely identify a build.

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.

slavename

This is a string which identifies which buildslave the build is running on.

scheduler

If the build was started from a scheduler, then this property will contain the name of that scheduler.

repository

The repository of the sourcestamp for this build

project

The project of the sourcestamp for this build