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

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:

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:

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:

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.