From AMCGMedia

Jump to: navigation, search

Launchpad is a general developer resource provided by Canonical, the company behind Ubuntu. It provides both code-hosting and package-building in Personal Package Archives (PPAs). To make use of Launchpad you will need to have a Launchpad account and will probably want to join one or more teams. This page aims to describe how you can set up an account and start using Launchpad.

After you are familiar with the basics of launchpad you may want to know about best practises for Local:Developing fluidity using bazaar and Local:Using branches in fluidity development.

Launchpad Memberships

Setting up a Launchpad account

Creating a new account

If you do not already have one, you can create a Launchpad account at:

https://launchpad.net/+login

Note - this is an OpenID login, so if you're already authenticating with OpenID you should be able to use that to authenticate to Launchpad.

Setting up your account

Once you've signed up and logged in, look to the top-right of the page and you'll see your username as a hyperlink. Click on this, and it will take you to your home page on Launchpad.

Setting up for code commits

If you're intending to commit code to launchpad you'll probably want to set up:

IRC - edit this to add your registered Freenode nick
SSH - you will almost certainly want to push your ssh public key for access to your Launchpad account when committing with bzr. bzr will prompt you to tell it your Launchpad username if you haven't already done so.

That should allow you to actively commit code, but if you also want to develop PPA packages you may want to also set up details as per the following section.

Setting up for PPA development

If you want to be active in developing AMCG packages you will need to edit fields as follows:

IRC - edit this to add your registered Freenode nick
PGP - you'll need to add a PGP key for signing packages; there is detailed information about setting up PGP keys in Ubuntu which should be immediately available as help items when you start to edit the PGP key entry.
Code of Conduct - to use PPAs you will need to PGP-sign the Ubuntu code of conduct.

This should be enough in your account to get up and running using PPAs.

Joining Teams

Teams are a way for developers to organise themselves around a project. There are a couple of teams which you may wish to join:

https://launchpad.net/~fluidity-core - the fluidity-core team for Fluidity developers, which most people probably do want to join if they've signed a Fluidity copyright form. Membership is required to be able to push changes to the trunk.
https://launchpad.net/~amcg - the AMCG packaging team, for those actively involved with maintaining the AMCG package sets. Most people probably don't want to join this unless they want to be active in systems administration work.

To join either, go to the team homepage and apply to join; this will be processed by one of the team admins.

Using Bazaar with launchpad

Setting up bzr

Tell bazaar who you are:

bzr whoami "John Doe <j.doe@imperial.ac.uk>"

Tell bazaar your launchpad id:

bzr launchpad-login john.doe

This is necessary to get a read/write Fluidity checkout where you can actually commit changes.

If you haven't told bazaar your launchpad id it will checkout a read-only copy via http. You can later change the binding of your checkout with:

bzr switch lp:fluidity

Getting Fluidity from Launchpad

Get a branch (unbound local copy) of the Fluidity trunk:

bzr branch lp:fluidity <target dir>

Get a checkout (bound local copy like in SVN) of the Fluidity trunk:

bzr co lp:fluidity <target dir>

This will branch / checkout Fluidity in the folder <target dir> or create a folder fluidity in your current directory if you do not give a target directory.

Setting up a shared repository

Mostly you will have several Fluidity branches living next to each other on your disk. Your layout might look like this:

fluidity/
  trunk
  my-feature-branch1
  my-feature-branch2
  ...

Bazaar allows sharing history between several related branches (and hence save space) through a shared repository. To benefit from that, create a shared repository in the fluidity folder with:

bzr init-repo fluidity

and subsequently branch / checkout Fluidity branches as subfolders of that shared repository.

Daily bzr

Local:Using Bazaar bzr

PPAs

Adding a PPA to your system

Adding PPAs to your system sources is easy! As long as you have the python-software-properties package installed, all you need to do is:

sudo apt-add-repository ppa:<account>/<ppa>

So for the fluidity and amcg repositories:

sudo apt-add-repository ppa:amcg/ppa
sudo apt-add-repository ppa:fluidity-core/ppa

That will both add source entries for apt and import the relevant keys for package installations. From the next update, packages from the PPA are available for installation and upgrade.

Working with a PPA

PPA activities are generally well documented within Launchpad. The two main PPAs for Fluidity and AMCG are:

https://launchpad.net/~amcg/+archive/ppa - AMCG packaging
https://launchpad.net/~fluidity-core/+archive/ppa - Fluidity supporting software

As a team member you should be able to work with one or the other or both of these repositories once you have set up your keys for signing packages. The following are draft notes to be refined on package building, updating, and maintenance.

Building for multiple targets

The Debian Policy Manual states that for a valid Distribution field':

In a .changes file or parsed changelog output this contains the (space-separated) name(s) of the distribution(s) where this version of the package should be installed. Valid distributions are determined by the archive maintainers. The Debian archive software only supports listing a single distribution. Migration of packages to other distributions is handled outside of the upload process.

This is a nuisance for us - Launchpad has similar restrictions in terms of the archive software only supporting listing a single distrubution. To get round this we use the following method.

A typical changelog entry when pushing a new package version will read something like:

fluidity-dev (1.0.55maverick1) maverick; urgency=low

  * Pushing to Launchpad PPA

 -- Tim Bond <timothy.bond@imperial.ac.uk>  Mon, 28 Feb 2011 11:57:17 +0000

Note the 'maverick1' suffix to the version, which would be changed to 'lucid1' along with 'lucid' as the distribution target for a package being pushed to Lucid rather than Maverick. The added number suffix is also useful as it allows trivial changes within a given version (for example, changing the packaging materials) to be easily pushed with an increment.

Once you've made a source package the target distribution will be pushed into the .changes file which is subsequently read by Launchpad to determine which builder to use.

Signing a source package with your own key

By default when you build a source package debuild will look for the key corresponding to the package maintainer. It may well be that you're acting on behalf of the package maintainer and thus using your own key. You can tell debuild to use your key as follows.

Get the fingerprint of your secret key:

tmb1@workstation:~$ gpg -K         
/home/tmb1/.gnupg/secring.gpg
-----------------------------
sec   2048R/87EF2124 2011-02-28
uid                  Timothy Bond <timothy.bond@imperial.ac.uk>
ssb   2048R/73BAE84F 2011-02-28

Look for the line starting 'sec' and the hex string in there, in this case '87EF2124'. Pass this to debuild withL

debuild -k0x87EF2124

and it should use your key to sign the source package.

Building the source package only

Debuild can make a range of packages; in this case we only want it to make the source package for upload to Launchpad. To do this, use '-S', giving:

debuild -k0xYOURKEY -S

You should then get a source package, the .changes file of which you can use to run dput and push the package to Launchpad.

Building a source package including the .orig.tar.gz file

In some cases a package will have a file ending '.orig.tar.gz' containing the clean version files to which patches, also included by the source package, will be applied. This needs a slight alteration to the debuild command to ensure that the .orig tarball is also uploaded, adding '-sa'. From the above, this gives:

debuild -k0xYOURKEY -S -sa

Using dput to push the package should now also push the orig.tar.gz file.

Pushing the source package

Pushing the source package needs 'dput' available, which is available on Ubuntu with:

wajig install dput

Once you have dput, just follow the instructions on the PPA's homepage, which will be something like:

dput ppa:amcg/ppa <source.changes>

In some circumstances, particularly after minor revision changes or when you're uploading for multiple distribution targets, you may find dput tells you that you have already uploaded the package and requires you to force the following upload. You can do this by adding '-f', as in:

dput -f ppa:amcg/ppa <source.changes>

Be careful with that, though - it may be telling you something useful rather than just getting in your way, for example that you've tried to push the wrong .changes file!

Working with the AMCG/Fluidity dependencies packages

Packages such as amcg-base and fluidity-dev have no contents other than their dependencies list, but you can to some extent treat them as normal packages for the purposes of working with them. Pick up a copy of the source with:

wajig source <package>

Then to tinker with it, cd into <package>/debian and edit files therein. The main file you will deal with is 'control' where the dependencies are specified. Once you've edited that, make sure to update the package version using:

dch -i

and editing the version line accordingly. Don't forget when you rebuild the package to make the appropriate edits for the other distribution versions too!

Using source package recipes for automated package builds

For building packages from source code hosted in bzr repositories and upload to a PPA, launchpad offers source package recipes, which automate builds in a very convenient way.

You need:

Source code to build in a bzr branch (ideally on launchpad)
Debian packaging information (i.e. the debian folder, if not already included in the source branch), ideally also as a bzr branch hosted on launchpad
a source package recipe, which is really easy to create
a launchpad source builder using the recipe

The process is very well documented in the launchpad manual and there is even a screencast demonstrating it.

Packaging the source code

Changes are the source code is already packaged and packaging branch is available on launchpad.

If the code you want to build is not packaged yet (or not yet available as a branch on launchpad), create a separate packaging branch of the code and follow the Ubuntu community's guide to packaging on how to populate the debian folder. Push this branch to launchpad as lp:~<user>/<project>/packaging.

It is good practise to have a separate branch for packaging and keep the trunk / upstream source branch free of packaging clutter. Alternatively, only the debian folder itself can be pushed as a branch. Packaging recipes can deal with either case easily by merging in the packaging branch or nesting it as the debian folder (see below).

Writing and testing the source package recipe

The recipe describes how to obtain a package from a set of bzr branches and how to name the resulting package in a very simple format descibed in detail in the launchpad recipe guide.

In the simplest case (when the source branch already contains packaging) this merely points to the branch to pull and specifies that packages are named as :

# bzr-builder format 0.4 deb-version {debupstream}+{revno}
lp:<project>

The last portion of the header specifies the package version, where {debupstream} extracts the upstream version number from the top entry of debian/changelog and {revno} is the bzr revision of the source branch. A suffix ~<ubuntu-release><counter> is automatically appended, such as ~oneiric1.

Usually we need to merge in the packaging branch:

merge packaging lp:~<user>/<project>/packaging

or nest it in if it's only the contents of the debian folder:

nest packaging lp:~<user>/<project>/packaging debian

In the same way you can merge in fixes:

merge fix-build lp:~<user>/<project>/<fix>

By default the latest revision will be pulled, but specific revisions can be specified by appending 'revno:n' to the branch specifier.

Before creating a builder, verify the the recipe builds sucessfully, running bzr-builder and pbuilder locally as described in the guide.

Setting up a launchpad builder

If the local build was successful, navigate to the source branch on launchpad and click (+) Create packaging recipe, fill in the description and paste your recipe.

To push to the AMCG Packaging PPA, you need to be a member of amcg on launchpad. For AMCG supporting software builds, you want to set the owner to amcg and the daily build archive to amcg/ppa. Initially set the build schedule to Built on request and request a build for all available Ubuntu distribution from Maverick and newer. If the build is successful you can later change it to Built daily.

Depending on Packages from a PPA

The target PPA and all the PPAs it depends on are included when retrieving build-dependencies for the recipe. To make sure the package from the PPA is picked (and not the one from the standard repositories) you may need to enforce the particular revision from the PPA for the dependency.

AMCG

Using Launchpad