ppa

Ubuntu's Personal Package Archive (ppa) is a great tool. I realize this now. But the overall concept isn't explained very clearly (in my opinion) so I shall rectify this, followed by some guidelines.

Please keep in mind that the scope of this post is for building packages already in Ubuntu's primary archives for backporting. This does not include building packages from scratch, patching the existing packages or installing them from a ppa.


(Simplified) Overall Concept
Ubuntu virtual machines will build packages for you after you have loaded the source code onto your computer, run a building command and then uploaded some of the resulting files to your ppa.

The ppa system will then schedule your build by ranking it against over things to be built. Packaging with higher importance, say security updates, will be ranked higher in the queue. Therefore, you may need to wait many, many hours.

The general order would be:
* prerequisites - having a launchpad account, establish gpg key and configuring your ppa and dput
* getting source code - downloading from Ubuntu's archives
* updating the changelog - incrementing the package revision
* building the package locally - debuild for dummies
* uploaded the changes file - dput dfile to dserver
* waiting for your ppa to build - tick, tick, tick

Prerequisites
There are several prerequisites than must be met before you can build a package. These include:
* having a Launchpad account
* creating a gpg key and registering it with Ubuntu
* signing the Ubuntu code of conduct
* configuring your dput
* creating your ppa

A very helpful (and verbose) post covering the first four bullet points and more can be found at the Ubuntu Forums [1].

You can create your ppa at your Launchpad page by clicking the Create New PPA link. The ppa name will be part of the link and used for dput, the display name is pretty trivial as is the description. When you are asked to give a ppa name I would suggest using something short since you may be typing it when you use dput.

Getting the Source Code
This is pretty straight forward: make a directory, change directories into it and download the source code.

mkdir ffado
cd ffado
apt-get source ffado

Updating the changelog
While not quite as succinct as getting the source code, this is still relatively short and simple.

After retrieving the source code you should have a new folder name source-version_number, change into this directory. Under this directory you will find a directory called debian, change into this directory. You should find a file called changelog. We will edit this file. Using the example of FFADO again:

cd libffado-2.0~rc1
cd debian
gedit changelog

A new entry will need to be made at the top of the file. Pay attention to the package version as shown in the ppa help page [2].

You name and email address must match your gpg key including any description you included when creating it. You can find this by typing gpg --list-keys.

The changelog also requires a very special time and date format. Use date -R to get the current time and date.

Lastly, follow the format of the previous entries for spacing and empty lines. If any formatting (including getting your name wrong) is incorrect the build process will blow up.

Building the Package Locally
Another simple step, but first make sure you are under the source code folder (but not the debian folder). For the example we would need to be directly under the libffado-2.0~rc1 folder. If you just changed the changelog:

cd ..

Now we need to run the debuild command:

debuild -S

This will read the changelog file you changed and create some new files with the new version number that will be used to upload to your ppa.

Uploading the Changes
When you creating your ~/.dput.cf file a name of your ppa was placed in brackets, this is the name you will use in your dput command. Here is my dput.cf file:

[hardybackports]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~slavender/ppa/ubuntu/
login = anonymous
allow_unsigned_uploads = 0

[build]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~slavender/build/ubuntu/
login = anonymous
allow_unsigned_uploads = 0

The first entry is for my original ppa which is named ppa (notice the ~slavender/ppa/ubuntu directory) and the hardybackports in the brackets. When I want to upload to my primary ppa I type dput hardybackports package_verison_source.changes which puts the code into my primary ppa.

The upload to my second ppa, notice the [build] and ~slavender/build/ubuntu, I type dput build package_verison_source.changes.

See the ppa help page [3] for more information.

Waiting for Your PPA to Build
There isn't much here to do other than find out how long you are expected to wait.

From you Launchpad page click on the link with your ppa name. Click on the link in the upper right that says View package details. Click the View all builds link at the upper right. Lastly pick package name link and the resulting page will have an approximate time until your build.

As mentioned at the beginning, build are ranked and built according to their respective ranks. More important ones (i.e. security) are ranked higher and therefore built earlier. The scheduling for this build is explained at the ppa help page [4].

Build times are approximate and conservative. I have found that they tend to move along pretty quickly. I don't recommend checking every five minutes but you may find that after an hour your time might have been reduced by two hours or more.

[1] http://ubuntuforums.org/showthread.php?t=929498
[2] https://help.launchpad.net/Packaging/PPA/BuildingASourcePackage
[3] https://help.launchpad.net/Packaging/PPA/Uploading
[4] https://help.launchpad.net/Packaging/BuildScores