Making a package for the Application Manager in maemo 3.x

This document is released under the GPL license.

Introduction

This guide explains how to make software packages that the end-user can install to the Internet Tablet using the Application Installer tool in the device.

This document has been reviewed for maemo 3.x and contains instructions that are spesific to Internet Tablet OS 2007 version, namely the new Single Click Install concept for applications.

Prerequisites

This document assumes that you are familiar with the process of how to create a .deb package. If debian packaging is new to you then a good place to start reading is the Debian Maintener's guide.

There is also the example "hello-world-app" package that you can use to get started. It is downloadable at hello-world-app_0.4.tar.gz.

The Application Installer

The Application Installer (also known as, AI) is a end-user friendly graphical frontend to the standard Debian package management infrastructure. When using the Application Installer the end-user does not have to use the apt-get tools.

The Application Installer 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 and make it accessible to apt.

You can freely use either Application Installer or the apt-get tool. Changes done to the system via apt-get or dpkg are picked up by the Application Installer without confusing it, and vice versa.

Compatibility between AI 2005, AI 2006 and AI 2007

Please refer to the older documentation if you need to know about the relationships between AI 2005 and AI 2006.

The AI 2006 is forwards compatible with AI 2007 but the new Single Click Install method that is introduced in AI 2007 is not working in AI 2006 or older versions.

Packaging

Packages made for the Application Installer should follow a few extra rules if they want to integrate nicely to the device. These rules are related to:

  • general stuff
  • dependencies
  • sections
  • icons
  • the installation/removal policy of the Application Installer
  • limited feedback to the user, no controlling terminal
  • warning about removing running applications
  • utilities to use in your maintainer scripts

These are explained in detail below.

General

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.

Dependencies

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.

Sections

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

The AI only shows packages in the "user" section. Thus, your "Section:" field in the control file should be of the form 

Section: user/<SUBSECTION>

where SUBSECTION is arbitrary. SUBSECTION should be a nice capitalised, English word like "Ringtones". There is currently no support for localising the SUBSECTION field.

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

The list of predefined subsections 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 subsection, 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

Icons

A package can have an icon that is displayed next to its name by the AI. 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.

You can see an example in the hello-world package:

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.

Installation and Removal Policy

The Application Installer 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 AI will never automatically remove a user package.

If a conflict caused by installing a package could be resolved by removing a package, the AI will not do the removal but will refuse the installation request instead.

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 AI to satisfy a dependeny, and are no longer needed.

Unfortunately, the AI is not very good in reporting conflicts: when your package conflicts with a non-user package, the problem reported by the AI 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 Installer runs your maintainer scripts, they have no controlling terminal; their standard input is connected to /dev/null. The DISPLAY variable is set correctly.

The Application Installer 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, it is the responsibility of the package creator (you!) to make sure that your mainter scripts do not fail. 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 Application Installer can run a script provided by your package before removing or upgrading it. That script can tell the Application Installer 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 Application Installer will run the program named, /var/lib/osso-application-installer/info/PACKAGE.checkrm, if it exists.
When this program exist 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: 

foobarexampleonly.checkrm remove

when the package is going to be removed, or 

foobarexampleonly.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: 

- maemo-select-menu-location <app>.desktop [default-folder]

When your package contains a .desktop file and consequently has an entry in the Desktop menu for this file, it can call maemo-select-menu-location in its postinst script to let the user choose a location for the entry.

The "app.desktop" parameter is the name of your .desktop file, without any directories. The default-folder parameter is optional, and when given determines the default folder of the menu entry. If you omit it, the menu entry will appear in "Extras".

The way to specify a folder that is provided by the system is by giving its logical name as listed in the /etc/xdg/menus/applications.menu file, NOT by giving its English name. Example logical names are 

tana_fi_games
tana_fi_tools
tana_fi_utilities

If you use a folder name that does not yet exist, it is created. In that case, you should NOT use a logical name, since there will likely be no translations available for that logical name. When creating a new folder, use a plain text name in a language that is appropriate. But, try to use existing folders as much as you can.

Thus, if your package installs the file, /usr/share/applications/hildon/foobarexampleonly.desktop and you want it to go to the "Utilities" menu, you would put this invokation into your postinst script: 

maemo-select-menu-location foobarexampleonly.desktop tana_fi_utilities

If you want it to go into a non-existing folder, use something like 

maemo-select-menu-location foobarexampleonly.desktop "Cute hacks"

In order to use maemo-select-menu-location in postinst, you should include Depends on the "maemo-select-menu-location" package.

You might want to skip calling maemo-select-menu-location when merely upgrading as opposed to installing from scratch. 

- maemo-application-running -x executable-file
  maemo-application-running -d app.desktop

This utility checks whether the application specified on the commandline is currently running. If it is running, it exits with code 0. If it is not running, it exits with code 1. If some error occured, it exits with code 2.

When using the -x option, the utility checks whether any process is currently executing that file, by looking into /proc/PID/exe.

When using the -d option, the utility uses the given .desktop file to find the service name of the application und queries D-BUS whether this service is currently registered. If there is no service name in the .desktop file, the utility uses the executable file as with the -x option.

In order to use maemo-application-running in postinst, you should include Depends on the "maemo-installer-utils" package. 

- maemo-confirm-text [title] file

Displays the contents of FILE in a dialog with "Ok" and "Cancel" buttons. The default title of the dialog is "License agreement".

When the user clicks "Ok", this utility exits with code 0; when he clicks "Cancel", it exits with code 1; and when an error occurs, it exits with code 2.

If you do in fact show a license agreement in your postinst script, it is probably not a good idea to make the postinst script fail when the user does not agree to the license terms. Instead, you could configure your application in such a way that it will ask the user to agree to the license agreement again when the application is started and refuse to run when he disagrees.

In order to use maemo-confirm-text in postinst, you should include Depends on the "maemo-installer-utils" package.

Single Click Install

NOTE: In OS 2007 this feature is still BETA.

In OS 2007 a new concept has been introduced to make installing applications easier for the typical end-user. This is called Single Click Install.

Please note that Single Click Install feature is not supported in the OS 2006 version

Normally, when you want end-users to be able to browse your repositories using the Application Installer, you need to provide instructions (on the web forexample) to the user how to configure your repository to the end-users device. On a fundamental level, you need to tell them what values to put into the "New repository" dialog.

Configuring repositories manually to the device can be error-prone and occasionally frustrating process for the typical end-user who might after a struggle give up installing the application in the first place.

The Single Click Install makes it easy to configure repositories to the device and installing new applications from previously unconfigured repositories to the Internet Tablet.

Now in OS 2007 release this manual task can be automated by providing a file of MIME type "application/x-install-instructions" and have the user open it with the Application installer. Files with the extension ".install" are recognized to have the mime type "application/x-install-instructions".

Such a .install file is a text file following the GKeyfile format, as defined by glib.

An example .install file that would add ONLY a repository entry to the devices /etc/apt/sources.list file would look like this: 

[install]
repo_name = Fooexampleonly Catalogue
repo_deb_3  = deb http://fooexampleonly.com/maemo bora extras

Thus, it can contain information about a repository, and opening the file will add the repository to devices /etc/apt/sources.list if it isn't there already.

The existence check is based on a simple string comparison without any intelligence: if you put two spaces in the "deb" line instead of one, the strings are considered different. This test might get smarter in the future.

To further make things simpler and more effortless for the end-user the .install file can also contain the actual name of the package. For example: 


[install]
repo_name = Fooexampleonly Catalogue
repo_deb_3  = deb http://fooexampleonly.com/maemo bora extras
package   = foosomething-app

Opening this file will attempt to install the package named "foosomething-app", after adding the specified repository assuming that it is not already configured in the device.

There is no guarantee, however, that the named package will actually be downloaded from the given repository. If the package is available with a later version from other repositories that are listed in sources.list, then it will be downloaded from there. This behavior is typical for the debian apt- tools.

The "repo_name" entry is optional. If you omit it, the repository will have no name. The name of a repository is only used in the UI; it has no effect on functionality.

The "repo_deb" entry is mandatory and it must point to valid existing address.

In fact, different releases of maemo will use different key names so that you can control what repository to use with what maemo release. If the expected repo_deb variant is not found in the .install file, an error message will be displayed to the user.

Here is a table of the various key names: 


maemo 2.0:  repo_deb
maemo 3.0:  repo_deb_3

In the above examples we used the new repo_deb_3 tag that means maemo 3.x (bora).

Signing a package

The GnuPG software delivered with the maemo rootstraps can not be used for package signing. If you want to sign your own software packages you need to use gnupg outside the Scratchbox environment.

Please refer to the official GnuPG website for instructions how to use the GnuPG tool.


Improve this page