Documentation/Maemo 5 Developer Guide/Packaging, Deploying and Distributing

=Packaging, Deploying and Distributing=

For installing and managing application packages, maemo uses the popular Debian package management system. Because the package management is performed using the Application Manager, it is invisible to the user. It presents a flexible package framework that enables developers to easily create installable and manageable packages, without having to concentrate on the actual implementation details of the management.

Deb Installation Packages

The Debian package management system uses deb-packages which contain the files to be installed, metadata describing the package, dependencies to other packages and optional installation and removal scripts. The process of creating the packages is fortunately made quite simple by various package development tools.

The process of creating packages is described in section Making Application Packages.

Package Repositories

The package management system makes use of package repositories, which are essentially web or FTP sites that contain packages and some information about them. Having a package reside in a repository brings significant advantages: the user can easily update packages, other developers can use the packages as automatically installable dependencies and the Application Manager can find the packages in the repository packages.

For more information on working with repositories, see the Debian Repository HOWTO.

One-Click-Install

Maemo also includes a option to create installation instruction files that enable the users to install applications simply by clicking a link on a web site. The .install files contain the required repository and package names. For more information on the format of these files, see section Controlling Installation.

Creating Debian Packages
To create a Debian package, the first step is to put all the files (the source code, and the png and other graphics, desktop and service files) in an empty directory called my-application-1.0.0. The directory name should follow the &lt;package-name&gt;-&lt;app-version&gt; convention; in other words, the package that is being created for this application is called my-application.

Go to the source directory: cd my-application-1.0.0

Set full name environment variable: export DEBFULLNAME="Your Name"

Make initial debianization: dh_make -e your.name@example.org

Next dh_make asks a question and prints a summary of the package: Type of package: single binary, multiple binary, library, kernel module or cdbs? [s/m/l/k/b] s Maintainer name : Your Name Email-Address  : your.name@example.org Date           : Fri, 30 Nov 2007 13:20:48 +0200 Package Name   : my-application Version        : 1.0.0 License        : blank Type of Package : Single Hit to confirm:

The dh_make command creates a Debian subdirectory containing multiple configuration text files. Most of them are templates that the application does not use; these can be removed. The following table lists the files you must keep:

The key files in ./debian are control and rules. They contain a generic template showing what they must look like. In control, fill in the blanks. In rules, remove any unwanted and unnecessary code.

The following example illustrates what the control file for the example application must contain: Source: my-application Section: user/other Priority: optional Maintainer: Your Name &lt;your.name@example.org&gt; Build-Depends: debhelper (&gt;= 4.0.0) Standards-Version: 3.6.0 Package: my-application Architecture: any Depends: ${shlibs:Depends} Description: A simple test application A very simple application with a short description. Which spans multiple lines actually. XB-Maemo-Icon-26: iVBORw0KGgoAAAANSUhEUgAAABoAAAAaCAYAAACpSkzOAAAABmJLR0QA/wD/AP+g vaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH1gURDQoYya0JlwAAAU9J REFUSMftlL1KA0EUhb/NZl/ggnHQxsJUxt5CUucVJCCkDfgyKdIGG5/A0s5HEBtJ EdDAQGBgmw0YJmMzgXXYza5CtNkDW9zZw5z7c+ZCgwb/Ai3i9sVl/Bq8RIs4LRK1 gJDsKvJyNXmJMuYTsMoY1zpgozaABdYArQNPZQ1kfyGU7SpqVwxzAMwABWhgpIwp 4vWBB+AUWAI3ypjnfEXtPU4bLKx9vErTeCeiRSYF+fTn1j5dp2myE9EiU+DSi3wX ymeqRQAmZ3EcA5E/fgO6BULT8zhOcrwXoJdrXRa2Lgps2y2odAUcBUIXQdz78YyC SldAp8b7+bXrIv91qjZBietqCc2DjbAt4b2WxJkyZljVujlwp0U0cPxuLcAIuC+4 dKxFlsDJarvdAGP/b6hFnDImYs+uG3hbO2AB3Jbsur63tQM+fFx3bzZocEB8AdV2 gJBZgKTwAAAAAElFTkSuQmCC

The XB-Maemo-Icon-26 field contains the application icon file (in this case, hello_icon_26x26.png) encoded in base64. The Application Manager displays this icon next to the package name. To perform this encoding in Linux, use either uuencode or openssl; however, more suitable applications may also exist. The following example encodes an icon file using uuencode inside Scratchbox:

[sbox-FREMANTLE_X86: ~] &gt; uuencode -m icon.png icon.png &gt; icon.png.en

In the above example, the result of the encoding is printed into icon.png.en file. Do not forget to put a white space at the beginning of each line containing the icon-encoded text. The white space indicates a multi-line field. The same rule stands for the long package description ( A very simple application[...]).

The Application Manager only shows packages in the user section. Thus, the Section: field in the control file must have the Section: user/&lt;SUBSECTION&gt; syntax, where &lt;SUBSECTION&gt; is arbitrary. See section [localhost#sec:making_app_pack_sections 17.2.6] for information on the suggested values.

Usually you do not have to change the rules file. However, if the new .deb package is empty, check the "install:" section to make sure that the DESTDIR environment variable is pointing to the where the other the packaging scripts are looking for the application to be packaged.

Once the application is properly 'Debianized', building the application is performed easily with the command:

[sbox-FREMANTLE_X86: ~/my-application-1.0.0] &gt; dpkg-buildpackage -rfakeroot

The system displays some output, including some warnings about XB-Maemo-Icon-26, but that is normal. The parent directory now contains a my-application_1.0.0-0_i386.deb file - the Debian package. This file is distributed to maemo devices and installed using the Application Manager.

To test the package in the SDK, type:

[sbox-FREMANTLE_X86: ~/my-application-1.0.0] &gt; cd .. [sbox-FREMANTLE_X86: ~] &gt; fakeroot dpkg -i my-application_1.0.0-0_i386.deb

Replace 'my-application...' with the actual name of the package. You can install packages in both X86 and ARMEL targets. Ensure that the package architecture matches the Scratchbox target.

For more information about making Debian packages, see Debian New Maintainers' Guide. For further information about creating application packages for maemo, see the next section [[#Making Application Packages|Making Application Packages].

 N.B.

If the application is deploying icons to /usr/share/icons/hicolor, run the gtk-update-icon-cache /usr/share/icons/hicolor command should be run in the postinst script to ensure that icons are displayed properly.

Making Application Packages
This section explains how to make software packages that the end user can install to the Internet Tablet using the Application Manager tool in the device.

Prerequisites
This section assumes familiarity with the process of creating a .deb package. For more information on the basics of Debian packaging, see section [localhost#sec:creating_debian_packages 17.1].

Use the "hello-world-app" example package to get started. To install it with apt-get, use the following command: apt-get source hello-world-app

Application Manager
The Application Manager (AM) is an end user friendly graphical front-end to the standard Debian package management infrastructure. When using the Application Manager, apt-get tools are not mandatory for the end user.

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

The usual way to distribute a package is to put it into a repository and make it accessible to apt.

Either Application Manager or the apt-get tool can be used freely. Changes made to the system via apt-get or dpkg are picked up by the Application Manager, and vice versa.

Packaging
Packages made for the Application Manager 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 Manager
 * limited feedback to the user, no controlling terminal
 * warning about removing running applications
 * utilities to use in the 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
This field should now contain all the dependencies for package, such as.

Sections
By default, the Application Manager only displays packages in certain sections to the user in order to hide the hundreds of system packages making up the IT OS itself. The AM is not intended to let the user manage the whole system at this point, only a smaller set of third-party applications.

The AM only shows packages in the "user" section. The "Section:" field in the control file should be in the following format:

Section: user/&lt;SUBSECTION&gt;

where SUBSECTION is one of:


 * 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 the package is wanted in the Office subsection, the field Section: user/office should be included in the control information.

Icons
The Application Manager may display an icon next to a package name. 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 understood by GdkPixbufLoader, but most commonly the PNG format is used.

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

The hello-world package shows an example.

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

Installation and Removal Policy
The 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 eliminate most surprises for simple package management operations, but this makes them less useable for complicated things like "apt-get dist-upgrade". Take these rules into account when designing the package conflicts.

Specifically, the AM never automatically removes a user package.

If removing a package can resolve a conflict caused by installing it, the AM refuses the installation request instead of performing the removal.

When removing a package, all packages that are a direct or indirect dependency of the removed package are considered for removal. Any non-user package automatically installed by the AM to satisfy a dependency and now no longer needes is removed.

Unfortunately, the AM is not very good in reporting conflicts: when the package conflicts with a non-user package, the problem reported by the AM considers the non-user package to be the source of the conflict, rather than any of the user packages that depend on it.

Feedback from Maintainer Scripts
When the Application Manager runs the maintainer scripts, they have no controlling terminal; their standard input is connected to /dev/null. The DISPLAY variable is set correctly.

The Application Manager collects a transcript of the installation/uninstallation process, including the output of maintainer scripts. This output is hidden in the application log which users are not meant to view and understand.

The package creator must ensure that the maintainer scripts do not fail. The best way is to try to execute operations that have a very high chance of succeeding. The simpler they are, the better.

Removing or Upgrading Running Applications
The Application Manager can run a script provided by the package, before removing or upgrading it. That script can tell the Application Manager to cancel the operation.

This feature is often used to display a warning if the user tries to remove or upgrade an application that is currently running. To perform this test, use the 'maemo-application-running' utility.

When uninstalling or upgrading a package named PACKAGE, the Application Manager runs the program named /var/lib/hildon-application-manager/info/PACKAGE.checkrm, if it exists. If this program exists with code 111, the operation is canceled. In all other cases, including when the program terminates with a signal, the operation is carried out.

Two arguments are available for the *.checkrm program. To remove the package, use the following:

foobarexampleonly.checkrm remove

To upgrade, use the following, replacing VERSION with the version information:

foobarexampleonly.checkrm upgrade VERSION

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

This utility is provided by the package hildon-application-manager-dbg. It checks whether the application specified on the command line is currently running. If the application is running, it exits with code 0. If it is not running, it exits with code 1. If an 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 und queries D-BUS whether the service is currently registered. If the .desktop file contains no service name, the utility uses the executable file like with the -x option.

maemo-confirm-text
maemo-confirm-text [title] FILE

This utility is provided by the package hildon-application-manager. It displays the contents of FILE in a dialog with "Ok" and "Cancel" buttons. The default title of the dialog is "License agreement".

If the user clicks "OK", the utility exits with code 0; if the user clicks "Cancel", it exits with code 1; and if an error occurs, it exits with code 2.

If a license agreement is not shown in the postinst script, ensure that even if the user does not agree to the licence terms, the postinst script does not fail. Instead, configure the application to ask the user to agree to the license agreement again at application startup and refuse to run if the user does not agree.

Controlling Installation
Application Installer (old name for Application Manager)had a beta stage Single Click Install feature. Application Manager is backwards compatible with it and the old .install files still work, but some new features are available.

The Application Manager offers three kinds of functionality with .install files: adding catalogues, installing packages from remote catalogues and installing packages from a memory card. The .install file follows the GKeyFile format as described by GLib. A GKeyFile consists of a number of groups, and each group contains key/value pairs. Each of the previously mentioned three functionalities is initiated by a specifically named group in the .install file.

Adding Catalogues
Adding catalogues is performed with the "catalogues" group. This group has one similarly named mandatory key, "catalogues". The "catalogues" key is a list of strings referring to the catalogue groups that describe the catalogues to be added. Each catalogue is considered in turn, and the user is asked whether to add it or not. If it is to be added, and if a matching catalogue is already configured in the Application Manager, the matching catalogue is removed first. If the user declines to add the catalogue, the next catalogue is considered. After asking confirmation for each catalogue, the device asks the user whether to "Refresh the list of applications". Here is an example:

[catalogues] catalogues = extras; sdk [extras] name = maemo Extras catalogue uri = http://repository.maemo.org/extras components = free non-free [sdk] name = maemo SDK catalogue uri = http://repository.maemo.org/ components = free non-free

A Group describing a catalogue can contain the following keys:


 * name: The display name of the catalogue as displayed to the user in the "Tool &gt; Application catalogues" dialog. Follow the GKeyFile conventions to localize this key. If this key is omitted, the catalogue contains an empty name.
 * uri: The URI part of the deb line that is added to sources.list for this catalogue. This key is required for all catalogues except those used with the "card_catalogues" key.
 * file_uri: When using file_uri instead of uri, the URI part of the deb line uses the "file://" method and the file_uri gives the actual pathname, relative to the location of the .install file. This key is required for all catalogues that are used with the "card_catalogues" key.
 * dist: The distribution of the deb line to be added to sources.list for this catalogue. If it is omitted, the catalogue defaults to the distribution corresponding to the IT OS release on the device. The Application Manager remembers to select the distribution automatically. For example, if a backup is made, containing a catalogue with automatic distribution selection, and restored on a different IT OS release, the distribution for the new version is used automatically.
 * components: The components part of the deb line to be added to sources.list for this catalogue. If it is omitted, the components part has no content.
 * filter_dist: Ignored if the distribution corresponding to the IT OS release on the device does not match.

When catalogues are compared, they are considered equal if their uri, dist and components fields are equal.

Installing Packages
In order to install packages with an .install file, the file must contain an "install" group. The group has one mandatory key, "package", and one optional key, "catalogues". The "catalogues" key is handled as follows: each catalogue is considered in turn. The user is asked for confirmation if a catalogue that is not already configured is encountered. Alternatively, if a catalogue is already present but disabled, the user is asked to confirm enabling the catalogue. If the user does not confirm, the processing of the .install file stops and any changes made in the configured catalogues are reverted. After the list of catalogues has been processed, the list of applications is refreshed automatically, and the package is offered to the user for installing. Here is an example:

[install] catalogues = foobar package = maemofoo [foobar] name = Foobar Catalogue name[en_GB] = Foobar Catalogue name[de_DE] = Foobar Katalog uri = http://foobar.com/repository components = main

Installing Packages from Memory Card
Installing packages from a memory card is governed by the "card_install" group. It has two mandatory keys, "packages" and "card_catalogues", and one optional key, "permanent_catalogues". The "packages" key lists the names of packages that can be installed from the memory card, using the "card_catalogues". The package is installed in a temporary environment where the usual catalogues are not available. Only the catalogues listed by the "card_catalogues" key are configured. All of these catalogues must use "file_uri" instead of "uri".

The user gets to select the packages from a list, after which the installation proceeds one package after another. In case the installation of a package fails, an error note is displayed, and the processing stops. After the installation is complete, the optional group "permanent_catalogues" is processed ???similarly to adding a catalogue as described above.

Whenever a memory card is inserted that contains a file called .auto.install, that file is processed by the Application Manager. Usually, the .auto.install file contains a "card_install" group, of course. For example:

$ mkdir .repo $ cp somewhere/*.deb .repo/ $ (cd .repo &amp;&amp; apt-ftparchive packages . &gt;Packages)

A matching .install file could look like the following:

[card_install] card_catalogues = repo packages = app-1; app-2 [repo] file_uri = .repo dist = ./

The .repo and the .install files typically go to the root of the memory card. To make the memory card auto-installing, make a copy of the .install file and name it .auto.install.

Signing Package
In order to sign packages, use debsign tool inside Scratchbox. For more information on using debsign, see the debsign manual page.

Installing Application Packages to SDK
Application packages can be installed into the maemo SDK using the Debian package manager called dpkg with root permission. [sbox-FREMANTLE_X86: ~] &gt; fakeroot dpkg -i application_i386.deb

Replace 'application' with the actual name of the package. You can install packages in both X86 and ARMEL targets. The package architecture must match the Scratchbox target.

Installing Application Packages to Device
You can also use the Debian package installer for installing application packages in Maemo devices. BusyBox v1.6.1 (2008-03-06 11:36:58 EET) Built-in shell (ash) Enter 'help' for a list of built-in commands. /home/user # dpkg -i application_armel.deb

For maemo device the package architecture must be always armel.

Red Pill Mode
The Hildon Application Manager has a special hidden mode that makes it more power-user friendly and gives access to features that are not yet considered ready for general distribution.

Activation
Go to the application menu by clicking on the Application Menu button (on the top left corner of the screen) -> App manager -> Click on the application manager window title area -> Click "Application catalogues" ->Click "New" Enter "matrix" into the "Web address" field and cancel the dialog by clicking on the area outside the dialog. Choosing Red pill activates red pill mode. Choosing Blue pill deactivates it.

Settings
After activating red pill mode, the application manager menu has two additional buttons : "Settings" and "Install from file".

Settings dialog has the following options:

Performs the equivalent of  after every install or update. (This is the behavior for blue pill mode.) Downloads without asking for an active IAP. This is useful if a network connection exists, but the device connectivity APIs are not available or do not know about it. Breaks locks as required instead of failing. This is the default behavior in blue pill mode so that, if a crash leaves a stale lock behind, users do not lock themselves out. Adds another tab to the details dialog with some dependencies from the package. Does not filter out packages that are not in the "user" section. Also allows installing packages from any section. Includes the "magic:sys" package in the list of packages. The effect of updating this package will resemble. Its exact behavior is not yet defined. This feature may become available in blue-pill mode in future.
 * Clean Apt Cache
 * Assume Net Connection
 * Break Locks
 * Show Dependencies
 * Show All Packages
 * Show Magic System Package
 * "Include package details in log"
 * "Use MMC to download packages"
 * "Always check for updates"
 * "Ignore packages from wrong domains"
 * "Ignore third party packages policy for SSU"
 * "Use apt-get algorithms"