0 votesclick to vote up

Michael Hall: Contributing to Ubuntu: A better Pkgme Published Jun 7 2012 via RSS

planetUbuntu

pkgme is a small utility created by James Westby, its purpose is to create a Debian package for any unpackaged applications.  It’s currently used when applications are submitted through the Ubuntu Developer Portal as tarballs, inspecting the contents of the application to determine how to build a package from it.  In order to support many different types and configurations of application, James built pkgme to support any number of different backends.

Currently there is support for apps using Python and Distutils, apps compiled by cmake, and apps written in Vala.  But there are still many, many applications out there that aren’t covered by these backends, including Qt apps, HTML5 apps, Flash apps and more.  That’s where you, dear contributor, come in.

But I don’t know how to create packages!

That’s okay, you don’t need to know how to make packages to create a pkgme backend.  It already knows how to make packages, what it doesn’t know is where to find the information it needs to do that.  This is what backends are, just one or more small scripts that extract enough information about a project to let pkgme do its thing.

Ok, I’m interested, how do I start?

First of all, get a copy of the latest pkgme code from its bazaar branch in Launchpad:

bzr branch lp:pkgme ./pkgme

Then, create a VirtualEnv environment to install it into:

virtualenv ./env

Then, install it into the Virtualenv:

source ./env/bin/activate
cd ./pkgme
python setup.py develop

Now you’ve got a working pkgme installed and running in your virtualenv. You can leave your virtualenv by running ‘deactivate’.  Time to get started on your backend!

Where do I put my new backend code?

Since we’re going to submit your new backend to the pkgme branch, we can just create it there:

cd ..
mkdir ./pkgme/pkgme/backends/<your backend name>

Great, now I have an empty Backend, what do I put here?

The first thing your backend needs is a ‘want’ file.  You see, in order for pkgme to know which backend it should use on any particular application, it needs to ask every backend how much they want it.  It does this by executing a script named ‘want’ in each backend.

Your want file is executed from the target application’s directory, so in your script ./ will be the root of the target application’s directory.  This lets you script easily browse through the files in the application to determine how well it can provide packaging information for it.

In order to tell pkgme how much your backend wants to handle the target application, your ‘want’ file simply needs to print a number to STDOUT.  The backend with the highest number is the one pkgme will use.  These are the suggested ranges for your ‘want’ value:

• 0 – no information can be provided about the project (e.g. a Ruby backend with a Python project).
• 10 – some information can be provided, but the backend is generic (e.g. Ruby backend).
• 20 – some information can be provided, and the backend is more generic than just language (e.g. Ruby on Rails backend).
• 30 – some information can be provided, and the backend is highly specialized.

Now I have what I want, what do I do with it?

Once pkgme has chosen your backend to use against an application, it will call one or more scripts from your backend to get information about the application.  As the backend author, you can choose to provide separate scripts for each piece of information, or you can provide just a single script called ‘all_info’ that will provide everything.

Lots of scripts

For separate scripts, you will need to provide an executable in your backend directory for each of the pieces of information that pkgme might request.  Each script should print that information to STDOUT, or exit with an error if it can not provide it.

Just one script

However, if looking up bits of information one at a time is a time-consuming task for your backend, you can do it all in one shot.  If you want to do that, then the only script you need is one called ‘all_info’.  When this script is called, it is also given a JSON list on STDIN.  This list contains the keys for all the pieces of information that pkgme needs from your backend.  As output, this scripts needs to print a JSON dictionary to STDOUT.  This dictionary should contain a key for each of the fields sent as input, along with its corresponding value.  If your backend can’t provide a value for one of those fields, it should be left out of the dictionary.

You can test your new backend by switching to the directory of a project your backend is made to support, and running:

pkgme

Make sure your virtualenv is still activated, or pkgme won’t be found. If everything works, you should have a ./debian/ directory in the application’s root folder.

Hurray, my backend works.  Do you want it?

Of course we want it!  What a silly question.  And it’s already in your local branch of pkgme too!  Well, it’s in the directory anyway, you still need to add it to the workingset:

cd ./pkgme/pkgme/backends/
bzr add <your backend name>

Then commit your changes and push them back to Launchpad:

bzr commit -m "Added backend for <your backend name>"
bzr push lp:~<your lp username>/pkgme/add-backend-<your backend name>

Then head on over to https://code.launchpad.net/pkgme, click on your new branch name, and then click the “propose for merging” link.  Fill out the description of what your backend adds, and submit it.  From there it will get reviewed by one of pkgme’s maintainers, and either get merged into the main branch, or sent back to you for fixes.