Packaging/SourceBuilds/Recipes

Not logged in - Log In / Register

Revision 18 as of 2014-08-25 08:24:02

Clear message

Launchpad Help > Packaging > Daily builds > Recipes

lp-diamond-16.png Source package recipes in Launchpad

Home

Getting Started

Knowledge Base

List of Daily Builds

Overview

A bzr-builder "recipe" is a description of the steps needed to construct a package from a set of Bazaar branches. Its format specifies:

Writing a recipe

Recipes have a simple format.

Note: you can find a typical example in the getting started guide.

They always start with a line similar to this:

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

Let's take a look at this in more detail:

Specifying the branches

The next line of a recipe specifies which branch to base the package on:

lp:bzr

This says that we will use the trunk of the bzr project in Launchpad. This could just as easily be any other branch in Launchpad, using the short format that you can find on any branch overview page.

Next, you can specify any number of other branches to include. There are two ways to include those branches additional branches:

Merging

Most often you'll use the "merge" command:

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

Here fix-build is a unique short name that we'll use to refer to this branch throughout the recipe. The short name can be anything you like, so long as it is unique to this branch within this recipe.

lp:~bzr/bzr/fix-build is the location of the branch.

In this example, the branch fix-build fixes a problem in the trunk that prevents it from building. This branch could be anything: stand-alone packaging information, some other modification to the branch that's not yet present in the trunk and so on.

Nesting

Nesting works in a similar way but has more scope:

nest pyfoo lp:pyfoo foo

The nest keyword puts the contents of one branch into a specific location in another branch, instead of merging it.

In this case, we are nesting the contents of lp:pyfoo in a new foo directory in the lp:bzr branch. Again, we've given the branch a short name, pyfoo, that we can use to refer to it throughout the recipe.

You can also act on the nested branch in the same way as you can the main branch: you can merge and nest other branches in your nested branch.

Here's how:

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

Any lines that are indented by two spaces, and are directly below your nest line, will act on the nested branch. In this example, the ubuntu-branding branch will be merged into pyfoo before it is nested in your primary branch.

nest-part

If you want to nest only one directory from another branch, you can use nest-part. It works in the same way as nest, except that you specify which directory you're taking from the nested branch.

For example:

nest-part packaging lp:~some-person/some-project/trunk-with-packaging debian debian

Packaging information

One of the branches that you include in your recipe must include packaging information in the debian directory. If it doesn't appear in one of the other branches you specify, you must specifically pull in a debian directory from elsewhere.

In our example recipe we'll use the nest-part above.

What our recipe looks like

Adding up all the lines above, our full recipe would look like this:

# bzr-builder format 0.3 deb-version 1.0+{revno}
lp:bzr
merge fix-build lp:~bzr/bzr/fix-build
nest pyfoo lp:pyfoo foo
  merge branding lp:~bob/pyfoo/ubuntu-branding
nest-part packaging lp:~some-person/some-project/trunk-with-packaging debian debian

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. For example:

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

Similarly for the main branch:

lp:bzr revno:1234

Bazaar allows you to tag a certain revision with an easily memorable name. You can request a specific tagged revision like this:

lp:bzr tag:2.0

Here, the recipe would use the revision that has the tag "2.0".

Version numbers and substitution variables

In the first line of the recipe, we specified a version number for the package we want to build, using:

deb-version 1.0+{revno}

Rather than specify a fixed version number, we need it to increase every time the package is built. To allow for this, you can use multiple substitution variables.

Variable

Purpose

Introduced in (recipe format version)

time

Replaced by the date and time (UTC) when the package was built.

0.1

revno

Replaced by the revision number.

0.1

latest-tag

Replaced by the name of the most recent tag

0.4

revdate

Replaced by the date of the revision that was built

0.4

revtime

Replaced by the time of the revision that was built

0.4

svn-revno

Replaced with the svn revision number of the revision that was built

0.4

git-commit

Replaced with the first 7 characters of the git commit that was built

0.4

debversion

Replaced with the version in debian/changelog

0.3

debupstream

Replaced by the upstream portion of the version number taken from debian/changelog. For example: if the version is 1.0-1, this would evaluate to 1.0.

0.1

debupstream-base

Similar to {debupstream}, but with any VCS identifiers (e.g. "bzr42", "svn200") stripped, and updated to always end with a "+" or "~")

0.3

All variables other than time are derived from a particular branch. By default they use the base branch (eg. {revno}), but they can also use a named branch (eg. {revno:packaging}).

debversion, debupstream and debupstream-base require debian/changelog to exist in the given branch. In recipe versions 0.3 and earlier, the changelog will be read from the final tree if the branch name is omitted.

The advantages of using {revno} and/or {time}:

You can use as many substitution variables as you like. For example:

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

Here the packaging in revno:packaging refers to the short name we gave the branch we're using for packaging.

This example would generate a package version something like:

1.0+4264-0ubuntu0+2145+200907201627

Next steps

Let's look at bzr-builder in more detail.

< Daily builds getting started

bzr-builder in detail >