Ubuntu Wiki

Launchpad Daily Builds and Rapid Feedback: Writing Recipe Builds - Instructors: jelmer

My name is Jelmer Vernooij. I currently work in the Bazaar team at Canonical, and before that I
worked on Launchpad. 
This app developer week session is going to be about source package recipe builds. 
I am going to assume that everybody here is familiar with at least basic Debian packaging. If you
are not, the Ubuntu packaging guide is a great start. See
http://developer.ubuntu.com/packaging/html/ 
You should also have some familiarity with a distributed version control system. Recipe builds on
Launchpad use Bazaar. A quick introduction about Bazaar can be found at
http://doc.bazaar.canonical.com/latest/en/mini-tutorial/ 
Please do interrupt me with questions if you have any. 
Today we are going to create a basic recipe for a small project. I have a project in mind
(pydoctor), but if somebody has other suggestions I am also happy to do another project (nothing
like living on the edge and doing this live). 
Does anybody have a suggestion for a project that doesn't take too long to build? 
Source package recipes are, like cooking recipes, a description of a set of ingredients (branches in
this case) and a description of how to meld them together. 
The result of a recipe is usually a Debian source package. 
You can write and build recipes locally by installing the "builder" plugin for Bazaar ("apt-get
install bzr-builder"). This is quite convenient when writing and testing recipes. 
Launchpad can also build recipes for you, and can directly upload the resulting source package to a
PPA. 
It can do this a single time, or you can have it build the recipe daily (as long as one of the
branches involved in the recipe has changed). 
This makes it very easy to do daily builds of a project, because Launchpad can automatically grab
the source code out of the upstream version control system, as long as Launchpad can import from the
upstream version control system. 
Once a recipe has been set up your PPA will automatically receive new packages, fresh from trunk,
every day. 
Does anybody have a suggestion of a project we should create a recipe for? 
I guess not, so let's go with pydoctor (a API documentation generator for Python). 
Every recipe has a "base" branch> This is usually the trunk of the upstream project you're building. 
In our case, it would be lp:pydoctor 
The upstream project does not contain any Debian packaging metadata, so we will also have to merge
that in. 
There happens to be a Debian package for pydoctor, so I have created an import of the Debian
packaging branch on launchpad - https://code.launchpad.net/~jelmer/pydoctor/unstable 
The last thing to consider is the version string. As we create the source package from multiple
branches, we don't want to just use the version in the last changelog entry of the packaging branch. 
If we did, that would mean that if the upstream branch changed and a new source package would be
built, that source package would have the same version string (but different contents). 
To work around this, bzr-builder will automatically add a new dummy changelog entry indicating that
a recipe build has been done, with a new version. 
TO give you a concrete example, let's look at the pydoctor recipe:
https://code.launchpad.net/~jelmer/+recipe/pydoctor-daily 
You can see the recipe text at the bottom of the page below "Recipe contents" 
As you can see, the first line describes the version string that will be added to the changelog. 
The second line contains the "base" branch, in this case lp:pydoctor 
and the third line specifies that the lp:~jelmer/pydoctor/unstable branch should be merged and can
be identified by the string "debian". 
The version string will be "0.3+bzr" followed by the last revision number of the base branch, then a
tilde and then the revision number of the packaging branch. 
You can see how the identifier for the third line comes in handy here. 
"merge" isn't the only supported command; other options are "nest" and "nest-part". There also more
variables available to use in the version string, such as {time} which will contain the current
time. See https://help.launchpad.net/Packaging/SourceBuilds/Recipes for a full list. 
if you put the contents of the recipe in a local file, you should be able to build it with
bzr-builder. 
For example, if you name this file "pydoctor.recipe" you can use: 
$ bzr dailydeb pydoctor.recipe build-pydoctor 
this will create a source package in the build-pydoctor directory. 
It is generally a good idea to test recipes locally first before adding them to Launchpad. That way
you don't have to wait for a slot in the build queue, and you save build resources on Launchpad. 
Did that work for everybody? 
once you have a working recipe, you can register it on Launchpad by clicking the "Create packaging
recipe" link on the branch page of one of the branches involved. 
There you'll have the chance to specify when the recipe should be built, what its instructions are,
and what PPA should be targetted. 
It is possible to specify what Ubuntu releases a recipe should be built for. Of course, you will
need to make sure that all of the build dependencies of your package are available in those releases
(or your PPA dependencies). 
After you have created a recipe, the page should look roughly like the one for my pydoctor recipe
(https://code.launchpad.net/~jelmer/+recipe/pydoctor-daily) 
If you have indicated that a recipe should be built daily, it will usually be built quickly after
you update one of its branches. 
Are there any questions so far? 
As I mentioned earlier, more information can be found on the Launchpad help pages:
https://help.launchpad.net/Packaging/SourceBuilds 
There is also a list of existing recipes that are in use on Launchpad,
https://code.launchpad.net/+daily-builds 
as you can see, we have about 400 that build on a daily basis 
That's about all I had. If you have questions about recipes, please ask them now or otherwise you
can always find me on this network under the nickname "jelmer" 
If you don't feel comfortable with recipe builds just yet, I can also recommend Matthew Revell's
video cast about source package recipe builds. 
http://www.youtube.com/watch?v=_bG-SXNX9Ww 
There are 10 minutes remaining in the current session. 
Thanks for your attention, happy hacking!