bzr-builder is a bzr plugin that helps you in setting up Packaging/SourceBuilds.

Installation

You can install it using the PPA at

• https://edge.launchpad.net/~dailydebs-team/+archive/bzr-builder

or by running

$ mkdir -p ~/.bazaar/plugins/
$ bzr branch lp:bzr-builder ~/.bazaar/plugins/builder

You can check it is installed by running

$ bzr plugins -v

and looking for "builder" in the listed plugins.

Getting Help

Help for the plugin is available by running

$ bzr help builder

and help for the individual commands is available as

$ bzr help build
$ bzr help dailydeb

Recipes

bzr-builder works with "recipes" that are descriptions of the steps needed to construct a package from the various bzr branches. You create one by writing a text file with a certain format.

The start of the file always looks similar to

# bzr-builder format 0.2 deb-version 1.0+{time}

The # bzr-builder format 0.2 is the same for each, and just specifies the version of the format in use. The current format is 0.2, and is increased as the format changes.

deb-version 1.0+{time} specifies the version to use for the generated package. {time} here is a substitution variable, more information on those will be given later.

The next line specifies the branch to base the package on:

lp:bzr

This says that we will use the trunk of the bzr project.

Then there is any number of other lines to specify other branches to include. The usual way to do this is to use the merge keyword to specify a simple merge of the branch.

merge fix-build lp:~bzr/bzr/fix-build

fix-build is the id of the branch within this file, it doesn't have to be the same as any part of the branch URL, but it has to be unique within the file. lp:~bzr/bzr/fix-build is again the location of the branch. What we are doing here is merging in a branch that we know we need in order to fix the build, but that hasn't landed in lp:bzr yet.

The other way to include code is to use the nest keyword.

nest pyfoo lp:pyfoo foo

The nest keyword specifies nesting another branch, instead of merging it. In this case we are nesting lp:pyfoo in to lp:bzr. We are using pyfoo to refer to it in the file, and we want it nested in the foo directory, so we specify that last.

It is possible to act on the nested branch in the same way as with the main branch. Any lines that are indented by two spaces under a nest line will act on the nested branch, e.g.

  merge branding lp:~bob/pyfoo/ubuntu-branding

would merge the ubuntu-branding branch in to foo.

The resulting branch needs to already have the debian directory in place with the packaging in it, as it can't be auto-generated. Therefore you will often need to merge one or more packaging branches:

merge packaging lp:~bzr/bzr/packaging

In total this recipe would look like

# bzr-builder format 0.2 deb-version 1.0+{time}
lp:bzr
merge fix-build lp:~bzr/bzr/fix-build
nest pyfoo lp:pyfoo foo
  merge branding lp:~bob/pyfoo/ubuntu-branding
merge packaging lp:~bzr/bzr/packaging

Specifying revisions

Sometimes you want to specify a specific revision of a branch to use, rather than the tip. You can do this by including a revision specifier at the end of any branch line, e.g.

merge packaging lp:~bzr/bzr/packaging revno:2355

or, for the first branch line

lp:bzr tag:1.0

would mean that every time the recipe was used it would use the "1.0" tag from that branch.

Version numbers

The deb-version specifier allow you to specify a version number for the resulting package, but it's not very useful if it is only ever a single version number, as you need it to increase.

The example above (1.0+{time}), use a substitution variable. This will be replaced when the version number is needed with the current date and time (UTC). This will ensure that later packages get higher version numbers.

There is a second variable that you can use as well: {revno}. This will be replaced the revision number of the revision that was used from the primary branch. You can use the revision number of any branch by using {revno:<branch id>}.

You can use as many substitution variables as you like, e.g.

  deb-version 1.0+{revno}-0ubuntu0+{revno:packaging}+{time}

Which would expand to something like

  deb-version 1.0+4264-0ubuntu0+2145+200907201627

Running Commands

Sometimes it is necessary to run a command in order to prepare a branch for packaging, and bzr-builder supports this. If you add

run autoreconf -i

at one point in the recipe it will run the command (autoreconf -i here) when it reaches that point while building the package.

It is recommended to avoid arbitrary network access, as you do not know the environment in which the command will be run.

Note that run can also be used in nest sections, where it will be run in the nested location.

nest packaging lp:~team/project/ubuntu debian
  run cat control

would run cat control in the debian directory.

The command is passed through the shell, so you can use shell constructs.

run touch a && touch b

If the command exits with a non-zero error code then it will stop the building of the package.

Building the recipe

In order to build the recipe you need to use the bzr dailydeb command.

$ bzr dailydeb package.recipe working-dir

This will perform the steps specified in package.recipe. It will create working-dir and put the resulting source tree and the source package there.

You can examine the unpacked source tree and then build the source package and install the results.