Hildon Application Manager

Overview  Development  Documentation  Testing 
2.1 (diablo, stable)  2.2 (fremantle, development) 
Packaging  Repositories  Installation scripts  Red pill mode 

How to make a package for the Hildon Application Manager

This is a short guide about how to make packages for the Hildon Application Manager. It is valid for Internet Tablet OS 2006 and later, but not for the old Internet Tablet OS 2005.

The main point to take away is that the Hildon Application Manager ("AM") is a graphical frontend to the standard Debian package management infrastructure, similar to Synaptic, but aimed at a different clientele.

The AM uses the same backend tools as Synaptic, Aptitude, or apt-get (namely libapt-pkg), and it does it in the standard way without imposing any constraints: packages are installed as root and can touch the whole system, for example.

The normal way to distribute a package is therefore to put it into some repository. See the here for more information on how to setup such a repository.

This HOWTO assumes that you are familiar with making .deb packages. A good place to start is the Debian New Maintainers' Guide.

You can freely alternate between the AM and apt-get, say. Changes done to the system via apt-get or dpkg are picked up by the AM without confusing it, and vice versa.

Packages made for the AM should follow a few extra rules, tho, if they want to integrate nicely. These rules are explained below.


All strings coming from the control information of a package are interpreted in UTF-8 when they are shown in the UI. If a string is not valid UTF-8, all bytes above 127 are replaced with '?' before displaying it.


The Application installer in the old Internet Tablet OS 2005 had a funny way to use the Depends control field in packages. Starting with the Internet tablet OS 2006, there is nothing special about the Depends control field anymore. It should no longer contain maemo. It should now contain all the real dependencies, like ${shlibs:Depends}, etc.

Segments and Sections

By default, the AM only shows packages in certain segments to the user. This has been done to hide the existence of the hundreds of system packages that make up the operating system itself. The AM is, at this point, not intended to let the user manage the whole system, only a smaller set of third party applications.

The AM only shows packages in the user segment. Thus, your Section field in the control file should be of the form

Section: user/SECTION

where SECTION is arbitrary. SECTION should be a nice capitalised, English word like "Ringtones". There is no support for localising that word yet, unfortunately.

However, there is also a predefined set of sections. If your package fits into one of these sections, you should put it there. This will avoid fragmenting the section names, and the names of these sections will be correctly localised.

The list of predefined sections and their English names is:

    user/accessories    Accessories        
    user/communication  Communication
    user/games          Games              
    user/multimedia     Multimedia         
    user/office         Office         
    user/other          Other                    
    user/programming    Programming        
    user/support        Support        
    user/themes         Themes         
    user/tools          Tools          

Thus, if you want to put your package into the Office section, include the field

Section: user/office

in your control information. If you want to put it into "Ringtones" (which is not pre-defined), use

Section: user/Ringtones

Additional control fields

The AM can make use of some additional fields in the control fields of a package. These fields generally start with a Maemo- prefix.

The way to get these fields into your .deb files is to include them with a XB- prefix in your debian/control file, see the Debian Policy Manual, section 5.7.

Pretty names

A package can specify a pretty name for itself. This name is displayed in the UI instead of the real package name.

The pretty name is specified with the Maemo-Display-Name field.

Upgrade descriptions

A package can specify a separate description to be used when it is displayed in the "Check for updates" view. This description should talk about what is new in this version of the package.

The upgrade description is specified with the Maemo-Upgrade-Description field. It is formatted like the normal Description field.

Localized names and descriptions

The Maemo-Display-Name, Description, and Maemo-Upgrade-Description fields can be provided in more than one language. The Application Manager first looks for a field named FIELD-LC where LC is the value of the LC_MESSAGES environment variable, and falls back to just FIELD when the localized field does not exist.

For example, when LC_MESSAGES equals de_DE, the Application Manager first tries Description-de_DE to find the short and long descriptions of a package.

Note that this way to localize package descriptions is different from what Debian is going to use. Instead of putting all the translations into the package metadata itself, Debian will provide translations in a separate directory of a repository and only the translations for the current language will be downloaded. This is clearly the way to go for a distribution with many packages and for supporting many languages.

In the future, the Application Manager will support this way of translating package descriptions and names as well, but for now, putting everything into the metadata directly is sufficiently easier to do and we shouldn't run into scalability problems just yet.


A package can have an icon that is displayed next to its name by the AM. Icons are included in the control information of a package as a base64 encoded field named Maemo-Icon-26.

The image format of the icon can be anything that is understood by GdkPixbufLoader, but is most commonly the PNG format.

The image should be 26x26 pixels with a transparent background.

Here is an example of a correctly formatted Maemo-Icon-26 field:



A package can specify certain flags, using the Maemo-Flags field. Most of these flags are intended for system upgrades.

The value of the Maemo-Flags field should be a comma separated list of one or more of the following words:

A operation usually involves more than one package and the flags of all packages are merged.

Required free space for installing

The AM does check if there is enough space before downloading the packages files.

It does not usually check if there is enough free space before installing a package, however. Doing so on a file system implementation that is compressed and very different from the one that has been used to compute the Installed-Size of a package is quite unreliable. Also, installation can take an unknown amount of storage space temporarily. The problem thus is that the Installed-Size doesn't really talk about how much space must be free in order for the installation to succeed.

As a fix, the AM allows you to explicitly specify how much space must be free by using the Maemo-Required-Free-Space field. When performing an installation or update, the values of the Maemo-Required-Free-Space fields of all involved packages is summed and the AM refuses to start the operation when the root partition doesn't have enough free space.

'Maemo-Required-Free-Space' should not include the size of the .deb package files themselves. The check whether there is enough space or not is done at two points: before downloading the packages, and before installing them.

Before downloading the packages, a check is made whether there is enough space for both the package files plus the required free space from their 'Maemo-Required-Free-Space' fields. The package files are downloaded to one of the available memory cards if necessary to ensure that enough space is available in the root filesystem afterwards.

Once the package files have been downloaded and before they are installed, the second check for the 'Maemo-Required-Free-Space' is performed.

Installation and removal policy

The Hildon Application Manager has its own rules for automatically installing and removing packages in addition to the ones specified by the user. These rules are tuned to give little surprises for simple package management operations, but in turn they are not really useable for complicated things like "apt-get dist-upgrade". When designing the conflicts of your packages, you might want to take these rules into account.

Specifically, the AM will never automatically remove a user package.

If a conflict caused by installing a package could be resolved by removing a package, the AM will not do the removal but will refuse the installation request instead. If you really want to remove a package, Conflict with it, and Replace it. Then the AM will remove it in favor of your package.

When removing a package, all packages that are a direct or indirect dependency of the removed package will be considered for removal. They will in fact be removed when they are a non-user package, have been automatically installed by the AM to satisfy a dependeny, and are no longer needed.

The AM is not very smart in reporting conflicts: when your package conflicts with a non-user package, the problem report by the AM will blame the conflict on that non-user package instead of on the user packages that depend on it.

Feedback from maintainer scripts

When the Application Manager runs your maintainer scripts, they have no controlling terminal; their standard input is connected to /dev/null. DISPLAY is set correctly, tho.

The AM collects a transcript of the installation/uninstallation process, including the output of maintainer scripts. However, this output is hidden away in the "Log", and you should not expect users to look there and understand its contents.

Thus, you should try really hard to not fail in your maintainer scripts. This does not mean that you should ignore errors, of course, but that you should only do things that have a very high chance of succeeding. The simpler, the better.

Warning about removing/upgrading running applications

The AM can run a script provided by your package before removing or upgrading it. That script can tell the AM to cancel the operation.

The canonical use for this feature is to warn the user when he tries to remove or upgrade an application that is currently running. You can use the utility maemo-application-running to perform this test. (See below for details.)

When uninstalling or upgrading a package named PACKAGE, the AM will run the program named


if it exists. When this program exits with code 111, the operation is cancelled. In all other cases, including when the program terminates with a signal, the operation is carried out.

The arguments given to the *.checkrm program are either

foo.checkrm remove

when the package is going to be removed, or

foo.checkrm upgrade VERSION

when it is going to be upgraded to version VERSION.

Utilities to use in your maintainer scripts

There are some utilities available that you can use in your maintainer scripts to interact with the user:

Other utilities