This page provides recipes for common tasks related to the packaging of component releases using Bazaar for inclusion in PPAs. We recommend the use of Bazaar for packaging of component releases because of the improved integration this provides with Ubuntu Distributed Development branches.

You will need the bzr, bzr-builddeb, and debhelper packages installed on your system to use these recipes. If your upstream branches are in git, you will also need the bzr-git package.

You will also need to configure bzr for use as described here, and to set up your Debian package building environment as follows:

  • set the DEBFULLNAME and DEBEMAIL variables in your enviroment as described in the dch(1) manpage

  • add this line to ~/.devscripts:

DEBCHANGE_RELEASE_HEURISTIC=changelog

(Although not the default, this option should always be used when your package is stored in a VCS.)

Initial packaging

The first step in creating a new package for a component release is to make sure you have a packaging branch derived from the upstream branch. This gives us access to the full upstream history for later reference, and lets us use standard VCS merge operations for integration of new upstream versions.

You only need to do this step once for a given component. Subsequent package revisions will reuse our packaging branch once created.

Creating your packaging branch

First we will create a bzr shared repository. This saves space by storing information about multiple branches in a single .bzr tree. We will want to create local mirrors of each upstream branch we work with; bzr can work directly against a remote branch over the network, but for some operations this can be very slow.

$ bzr init-repo u-boot
$ cd u-boot

Branching from git

If you have a git repository where HEAD points at the branch containing the releases you intend to package, and this branch will not be rebased and does not contain references to git submodules, you can initialize your packaging branch like this:

$ bzr branch git://git.linaro.org/boot/u-boot-linaro-stable.git upstream
$ bzr branch -r tag:v2010.12 upstream packaging
$ cd packaging

where v2010.12 refers to the git tag of the release you are packaging.

Branching from bzr

If the upstream sources are available in bzr, you can of course branch as you would from any other branch.

$ bzr branch bzr+ssh://bazaar.launchpad.net/u-boot-linaro/trunk upstream
$ bzr branch -r tag:v2010.12 upstream packaging
$ cd packaging

or

$ bzr branch lp:u-boot-linaro upstream
$ bzr branch -r tag:v2010.12 upstream packaging
$ cd packaging

where v2010.12 refers to the bzr tag of the release you are packaging.

No available upstream branch

If all else fails (there is no upstream VCS branch to pull from, or bzr doesn't support pulling from this VCS branch), it is still worthwhile to create a bzr branch for your packaging, to preserve complete history of the packaging and better integrate with UDD even if the upstream history will not be visible in detail.

$ tar zxvf u-boot-linaro_2010.12.tar.gz
$ mv u-boot-linaro-2010.12 packaging
$ cd packaging
$ bzr init
$ bzr add
$ bzr commit -m "initial upstream import"

Creating the source package

Once you have a bzr branch containing your upstream sources, there are five files you must populate to create a viable initial source package. Four of these can be created from the commandline; the fifth, debian/control, must be created by hand.

$ mkdir -p debian/source
$ echo '3.0 (quilt)' > debian/source/format
$ echo 7 > debian/compat
$ cp /usr/share/doc/debhelper/examples/rules.tiny debian/rules
$ dch --package u-boot-linaro --version 2010.12-0linaro1 --create 'Initial package'

You will then need to create debian/control by hand for your package. The format of this file is defined here.

You will also need to have the upstream tarball release present in the parent directory. The tarball must be named <package>_<upstream version>.orig.tar.{gz,bz2} - e.g., u-boot-linaro_2010.12.orig.tar.gz.

Once you have these files, you can generate a preliminary source package with debuild:

$ debuild -uc -us -S -i

Importing the source into bzr

Finally, now that we have both a bzr branch and a Debian source package, we import the source package into the branch. This also stores the upstream tarball in the branch as a binary diff against the upstream tree using pristine-tar, so afterwards other developers only need to grab the branch to work with the package - they don't need to grab the upstream tarball separately.

$ rm -r debian
$ bzr import-dsc ../u-boot-linaro_2010.12-0linaro1.dsc

For more examples of creating initial packages with bzr-builddeb, see http://www.advogato.org/person/robertc/diary/130.html and http://web.dodds.net/~vorlon/wiki/blog/bzr-git_case_study.html. For a more detailed walk-through of creating a package from scratch, see http://wiki.debian.org/IntroDebianPackaging.

Branching an existing package

Sometimes Linaro component releases will be made for software that is already packaged in Ubuntu. In this case, it may be advantageous to base our package branch on the existing UDD branches to facilitate merge requests with Ubuntu. However, in most cases an existing UDD branch will not share revision history with the upstream branch, so you will be unable to see detailed upstream history when using this method. In this way the results are similar to what's described above.

$ bzr init-repo u-boot
$ cd u-boot
$ bzr branch lp:ubuntu/u-boot packaging
$ cd packaging

Publishing your package branch

Once you have created a branch for your packaging changes, you should publish it to launchpad. If this branch is for a package that already exists in Ubuntu, you can publish directly to a UDD branch:

$ bzr push lp:~<username_or_team>/ubuntu/<release>/<package>/<branch_name>

e.g., to push a package branch corresponding to the toolchain WG's maverick ppa, you might use:

$ bzr push lp:~linaro-toolchain-wg/ubuntu/maverick/qemu-linaro/ppa

In many cases, you will be creating branches for packages not yet part of Ubuntu and you will need a place to publish branches of your work in progress. For this we can use launchpad's +junk feature.

$ bzr push lp:~linaro-toolchain-wg/+junk/qemu-linaro-packaging

Once the package has been accepted into Ubuntu and a UDD branch exists, we can overwrite it with our branch which contains the full history.

$ bzr push --overwrite lp:ubuntu/natty/qemu-linaro

/!\ Note: the source branch *must* have correct tags for each upstream release and Ubuntu package revision that has been uploaded to the archive if you do this!

When official packages will be built from your package branch, whether for Ubuntu or for a Linaro PPA, you should set the Vcs-Bzr field in debian/control to point to the official location of this branch. This allows users to find the correct source for your package.

Merging a new upstream release

When a new upstream release has been made for the component, we will want to make packages of it, merging the information about the new upstream version into our branch - both the commit history, and the release tarball itself. There must be an upstream tarball for each new upstream version we create a package for, where "upstream version" is defined as the part of the version number in debian/changelog before the final dash. If there are no upstream tarball releases for this component, either you need to synthesize one for packaging purposes, or you should not increment the upstream version number and instead handle this as a case of merging unreleased changes from the upstream VCS.

Using uscan

The uscan tool uses debian/watch files to automate the process of finding and downloading new upstream releases and renaming the tarballs so they can be found by the rest of the packaging tools. Even if you are releasing the upstream tarball yourself and don't need to use uscan to download it, it's recommended to provide a debian/watch in your package for others to use.

Here is a sample watch file for a project released on Launchpad, with options to control the mapping between upstream and package version numbers:

version=3
opts=uversionmangle=s/-rc/~rc/,dversionmangle=s/\+dfsg\d*$// \
https://launchpad.net/qemu-linaro/+download http://launchpad.net/qemu-linaro/11\.05/.*/\+download/qemu-linaro-(.+).tar.gz

Using uscan to grab a tarball is as simple as:

$ cd qemu-linaro/packaging
$ uscan
qemu-linaro: Newer version (0.13.50-2011.02-0~rc2) available on remote site:
  http://launchpad.net/qemu-linaro/11.05/2011.02-rc2/+download/qemu-linaro-0.13.50-2011.02-0-rc2.tar.gz
  (local version is 0.13.50-2011.02-0~rc1)
qemu-linaro: Successfully downloaded updated package qemu-linaro-0.13.50-2011.02-0-rc2.tar.gz
    and symlinked qemu-linaro_0.13.50-2011.02-0~rc2.orig.tar.gz to it
$

When upstream doesn't release a tarball

To use this packaging method, you must have a tarball representing the upstream release. However, it's not required that the tarball be officially released by upstream. If upstream does VCS-tag-only releases, you can use a make dist target or similar to create a tarball matching the release tag. This tarball will be reused for all subsequent package revisions based on this upstream version.

bzr merge-upstream

Once you have the upstream tarball in the parent directory, use bzr merge-upstream to merge the new release into your package branch.

$ bzr merge-upstream --v3 --version 0.13.50-2011.02-0~rc2 \
    ../qemu-linaro_0.13.50-2011.02-0~rc2.orig.tar.gz -r tag:2011.02-0-rc2 ../upstream
[...]
Committed revision 2.                                                          
Warning: criss-cross merge encountered.  See bzr help criss-cross.             
Text conflict in hw/slavio_intctl.c                                            
Text conflict in qemu-lock.h
2 conflicts encountered.                                                       
The new upstream version has been imported.
You should now resolve the conflicts, review the changes, and then commit.
$

bzr merge-upstream will automatically create a new changelog entry for your merge in debian/changelog. If your package will be uploaded to a ppa rather than to Ubuntu, you should update the changelog to have a distinguishing version number by running dch with a -l option; e.g.,

$ dch -l ~ppa

merge-upstream only needs to be done once per release for a related set of UDD branches; other branches can (and should) merge the result from there.

Merging unreleased changes from upstream VCS

You can also merge not-yet-released changes from the upstream branch using an ordinary bzr merge command.

$ cd u-boot/upstream
$ bzr pull
$ cd ../packaging
$ bzr merge ../upstream
$

Use -r options to limit which revisions are merged from upstream:

$ bzr merge -r git:dee5e9ff ../upstream

You can also use bzr merge to cherry-pick individual commits from upstream by specifying a range of revisions. Bear in mind that this will cause conflicts later when doing a full merge; bzr will not track the fact that these revisions were previously cherry picked.

Uploading a package

When you upload a package to Ubuntu or to a ppa, you should update the package branch at the same time to show that the package has been released. You should only need to do this if you are the uploader of the package; normally you do not need to mark the package as released if you are submitting a merge request instead.

First use dch -r to mark the package as released. You can pass a -D option to specify an upload target (i.e. Ubuntu release) other than the default.

$ dch -r -D maverick

Then commit your change and create the tag for the release.

$ debcommit -r

You can also commit with bzr commit if you prefer, and use bzr mark-uploaded to create the correct tag for the release.

Next, build the source package and push the branch up to Launchpad.

$ bzr bd --source
$ bzr push

Finally, upload the package with dput.

$ dput ppa:linaro-toolchain-wg ../qemu-linaro*source.changes

More information

For more information about using Bazaar in Linaro, see Resources/HowTo/BZR.


CategoryBzr

Platform/DevPlatform/ComponentReleasesWithBzr (last modified 2011-03-17 16:49:34)