Making application packages

This document is released under the GPL license.

Introduction

This document provides instrucions on how to make packages for the Application Installer (AI) of the Internet Tablet OS 2006.

AI 2006 is a graphical frontend to the standard Debian package management infrastructure.It is similar to Synpatic, but aimed at a different clientele.

The normal way to distribute a package is to put it into a repository and make it accessible to apt. For more information on how to set up such a repository, see http://www.debian.org/doc/maint-guide/.

The AI 2006 uses the same backend tools as Synaptic, Aptitude, or apt-get (namely libapt-pkg), The AI 2006 uses these tools in the standard way, without imposing any constraints. For example, packages are installed as root and are cabable of touching the whole system.

This document requires that you are familiar with making .deb packages. For more information on making the .deb packages, see Debian New Maintainer's guide.

Also, there exists an example "hello-world-app" package, which you can use to get started. It is downloadable at hello-world-app_0.4.tar.gz.

Note that you can freely alternate between AI 2006 and apt-get, for example. Changes done to the system via apt-get or dpkg are picked up by the AI 2006 without confusion to the system, and vice versa.

To ensure integration, packages made for the Application Installer 2006 need tofollow a few extra rules. These rules are related to:

  • Relationship with Application Installer 2005
  • Characters
  • Dependencies
  • Sections
  • Icons
  • The installation/removal policy of the AI
  • Limited feedback to the user and no controlling terminal
  • Warning about removing running applications
  • Utilities to use in your maintainer scripts

Relationship with Application Installer 2005

The Application Installer 2006 is very different from the one in Internet Tablet OS 2005 (IT 2005) and the two are not compatible. If you have packages that work with IT 2005, you need to redo their packaging in order to make them work with IT 2006. IT 2005 and IT 2006 are not binary compatible with each other, so they require separate packages.

The Application Installer 2005 will reject packages made for 2006 and vice versa.

The two versions of the AI (2005 and 2006) differ visually, so there is no real risk in confusing the two. The AI 2005, for example, is a Control Panel applet, and the AI 2006 is a regular application started from the Tools menu. Also, the AI 2006's UI is called "Application Manager".

Characters

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 '?' on the display.

Dependencies

In AI 2006, the "Depends" control field does not contain "maemo". Instead, it now contains all the real dependencies, such as ${shlibs:Depends}.

Sections

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

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

	Section: user/

In the example, SUBSECTION is arbitrary. SUBSECTION can be, for example, Ringtones. There is no support for localising that word yet, which requires you to use proper English words.

There is also a predefined set of subsections. If your package fits into one of these subsections, put it into that subsection. By doing this, you avoid fragmenting the subsection names, and the names of these subsections will be correctly localised.

The list of predefined subsections and their English names consists of the following:

  • 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

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 section), use Section: user/Ringtones.

Icons

A package can have an icon that is displayed next to its name by the system. 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 the GdkPixbufLoader understands, but the most commonly used format is PNG.

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

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

The way to include these fields into your .deb files is to include them with a "XB-" prefix in your debian/control file. For more information, 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 designed to ensure that there are no surprises for simple package management operations, but in turn they are not useable for more complicated operations such as "apt-get dist-upgrade". When designing the conflicts of your packages, you might want to take these rules into account.

Specifically, the AIl never automatically removes a user package.

If a conflict caused by installing a package could be resolved by removing a package, the AI will not perform the removal. Instead, it refuses the installation request.

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

The AI is not smart in reporting conflicts: when your package conflicts with a non-user package, the problem report 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. Note that DISPLAY is set correctly.

The Application Installer collects a transcript of the installation/uninstallation process, including the output of maintainer scripts. However, this output is storedin the "Log". Do not expect users to look there to understand the contents of the file.

Therefore, concentrate on making functional maintainer scripts. This does not mean that you can ignore errors, instead, design code that has a high chance of succeeding. The simpler the scripts are, the better user experiencec are expected.

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.

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:

 	foo.checkrm remove

for when the package is going to be removed, or:

 	foo.checkrm upgrade VERSION

for when it is going to be upgraded to version VERSION

Utilities to use in your maintainer scripts

There are the following utilities available, which you can use in your maintainer scripts to interact with the user: 

	- maemo-select-menu-location .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. Examples of 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, do NOT use a logical name, since there are no translations available for that logical name. When creating a new folder, use a plain text name in a language that is appropriate. In addition, try to use existing folders as much as you can.

Thus, if your package installs the file /usr/share/applications/hildon/foo.desktop and you want it to go to the "Utilities" menu, include the following invocation into your postinst script: 

 	maemo-select-menu-location foo.desktop tana_fi_utilities

If you want it to go into a non-existing folder, use something similar to the following example: 

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

In order to use the maemo-select-menu-location in postinst, use Pre-Depend on the maemo-select-menu-location package.

Consider skipping calling the maemo-select-menu-location when merely upgrading, as opposed to installing from scratch. For example: 

 	- 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 occurs, 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, and queries D-BUS whether this service is currently registered or not. 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 the maemo-application-running in postinst, use Pre-Depend on the maemo-installer-utils package. For example: 

 	- maemo-confirm-text [title] file

This 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; and if the user clicks Cancel, it exits with code 1. When an error occurs, it exits with code 2.

If you do in fact show a license agreement in your postinst script, it is not a good idea to make the postinst script fail if the user does not agree to the license terms. Instead, you can configure your application in such a way that it asks the user to agree to the license agreement again when the application is started, and refuses to run if the user disagrees.

In order to use maemo-confirm-text in postinst, use Pre-Depend on the maemo-installer-utils package.


Improve this page