builder - Construct a branch from a recipe

Version Not specified
Branch lp:bzr-builder
Home page
Owner james-w
GNU/Linux Yes
Windows Yes
Mac OS X Yes

The bzr-builder plugin allows you to construct a branch from a ‘recipe’.

The recipe is a series of pointers to branches and instructions for how they should be combined. There are two ways to combine branches, by merging, and by nesting, allowing much flexibility.

A recipe is just a text file that starts with a line such as:

# bzr-builder format 0.3 deb-version 1.0+{revno}-{revno:packaging}

The format specifier is there to allow the syntax to be changed in later versions, and the meaning of “deb-version” will be explained later.

The next step is the define the base branch, this is the branch that will be places at the root, e.g. just put:


to use the trunk of “foo” hosted on Launchpad.

Next comes any number of lines of other branches to be merged in, but using a slightly different format. To merge a branch in to the base specify something like:

merge packaging lp:~foo-dev/foo/packaging

which specifies we are merging a branch we will refer to as “packaging”, which can be found at the given URI. The name you give to the branch as the second item doesn’t have to match anything else, it’s just an identifier specific to the recipe.

If you wish to nest a branch then you use a similar line:

nest artwork lp:foo-images images

This specifies that we are nesting the branch at lp:foo-images, which we will call “artwork”, and we will place it locally in to the “images” directory.

You can then continue in this fashion for as many branches as you like. It is also possible to nest and merge branches into nested branches. For example to merge a branch in to the “artwork” branch we put the following on the line below that one, indented by two spaces:

merge artwork-fixes lp:~bob/foo-images/fix-12345

which will merge Bob’s fixes branch into the “artwork” branch which we nested at “images”.

It is also possible to specify a particular revision of a branch by appending a revisionspec to the line. For instance:

nest docs lp:foo-docs doc tag:1.0

will nest the revision pointed to by the “1.0” tag of that branch. The format for the revisionspec is identical to that taken by the “–revision” argument to many bzr commands. See “bzr help revisionspec” for details.

You can also merge specific subdirectories from a branch with a “nest-part” line like

nest-part packaging lp:~foo-dev/foo/packaging debian

which specifies that the only the debian/ subdirectory should be merged. This works even if the branches share no revision history. You can optionally specify the subdirectory and revision in the target with a line like

nest-part libfoo lp:libfoo src lib/foo tag:release-1.2

which will put the “src” directory of libfoo in “lib/foo”, using the revision of libfoo tagged “release-1.2”.

It is also possible to run an arbitrary command at a particular point in the construction process. For example:

run autoreconf -i

will run autotools at a particular point. Doing things with branches is usually preferred, but sometimes it is the easier or only way to achieve something. Note that you usually shouldn’t rely on having general Internet access when assembling the recipe, so commands that require it should be avoided.

You can then build this branch by running:

bzr build foo.recipe working-dir

(assuming you saved it as foo.recipe in your current directory).

Once the command finished it will have placed the result in “working-dir”.

It is also possible to produce Debian source packages from a recipe, assuming that one of the branches in the recipe contains some appropriate packaging. You can do this using the “bzr dailydeb” command, which takes the same arguments as “build”. Only this time in the working dir you will find a source package and a directory containing the code that the packages was built from once it is done. Also take a look at the “–key-id” and “–dput” arguments to have “bzr dailydeb” sign and upload the source package somewhere.

To build Debian source package that you desire you should make sure that “deb-version” is set to an appropriate value on the first line of your recipe. This will be used as the version number of the package. The value you put there also allows for substitution of values in to it based on various things when the recipe is processed:

  • {time} will be substituted with the current date and time, such as 200908191512.
  • {date} will be substituted with just the current date, such as 20090819.
  • {revno} will be the revno of the base branch (the first specified).
  • {revno:<branch name>} will be substituted with the revno for the branch named <branch name> in the recipe.
  • {debupstream} will be replaced by the upstream portion of the version number taken from debian/changelog in the final tree. If when the tree is built the top of debian/changelog has a version number of “1.0-1” then this would evaluate to “1.0”.

Instruction syntax summary:

  • run COMMAND

Format versions:

0.1 - original format. 0.2 - added “run” instruction. 0.3 - added “nest-part” instruction.



Build a tree based on a ‘recipe’.




-v, --verbose Display more information.
 Only build if the outcome would be different to that specified in the specified manifest.
-q, --quiet Only display errors and warnings.
 Path to write the manifest to.
--usage Show usage message and options.
-h, --help Show help message.


Pass the name of the recipe file and the directory to work in.

See “bzr help builder” for more information on what a recipe is.



Build a deb based on a ‘recipe’.




-v, --verbose Display more information.
--package=ARG The package name to use in the changelog entry. If not specified then the package from the previous changelog entry will be used, so it must be specified if there is no changelog.
 Only build if the outcome would be different to that specified in the specified manifest.
--safe Error if the recipe would cause arbitrary code execution.
-q, --quiet Only display errors and warnings.
 Path to write the manifest to.
--no-build Just ready the source package and don’t actually build it.
--dput=TARGET dput the built package to the specified dput target.
 Append the specified string to the end of the version used in debian/changelog.
--usage Show usage message and options.
 The distribution to target. If not specified then the same distribution as the last entry in debian/changelog will be used.
-k ARG, --key-id=ARG
 Sign the packages with the specified GnuPG key. Must be specified if you use –dput.
--watch-ppa Watch the PPA the package was dput to and exit with 0 only if it builds and publishes successfully.
-h, --help Show help message.


See “bzr help builder” for more information on what a recipe is.

If you do not specify a working directory then a temporary directory will be used and it will be removed when the command finishes.

Table Of Contents

Previous topic

undelete - Undelete to last known version of files/dirs

Next topic

externals - External branches ala Subversion

This Page