Documentation/Maemo 5 Developer Guide/Packaging, Deploying and Distributing
Adding software to Maemo is done through "packages". Packages are discreet archives of applications and additional information that make installing software easier than compiling the software from scratch. To install and manage packages on Maemo devices, Maemo uses the Debian package management system APT, the Advanced Packaging Tool. APT is the underlying system which the developer fits their package into. Adding and removing software on Maemo devices is done using the Application Manager, which works with the APT system, making the details of installing packages invisible to the user. You can consider APT as the backend and Application Manager as the frontend. The combination of APT and the Application Manager presents a flexible framework that enables developers to easily create packages and simplify installation of software for the user.
Debian Packages, or debs
The APT package management system, developed by Debian, manipulates 'debs'. Debs are simple binary archives which contain the files to be installed, metadata describing the deb, dependencies on other software, and optional installation and removal scripts. The process of creating a deb is fortunately made quite simple by various tools.
This process is described in section Creating Debian Packages.
Package Repositories
The package management system makes use of package repositories, which are essentially web or FTP sites that contain packages and make them available for download. Having a package reside in a repository brings significant advantages: the user can easily update packages on their device by downloading new packages from the repository, other developers can use the packages as automatically installable dependencies and the Application Manager can find the packages in the repository using a URL.
For more information on working with repositories, see the Debian Repository HOWTO.
One-Click-Install
Maemo provides the option of creating installation instruction files that enable users to install applications simply by clicking a link on a web site. This is often a very easy process for the user and it is highly recommended that the developer creates these files. The .install files contain the required repository and package names. For more information on the format of these files, see section Controlling Installation.
[edit] Creating Debian Packages
To create a Debian package, the first step is to put all the files (source code, graphics, desktop and service files) in an empty directory called my-application-1.0.0. The directory name should follow the <package-name>-<app-version> convention; in other words, the package that is being created for this application is called my-application. See the Debian New Maintainer's Guide for more information on naming rules.
Go to the source directory:
cd my-application-1.0.0
Set full name environment variable:
export DEBFULLNAME="Your Name"
Initial Debianization. dh_make command is available from debhelper package and should be enabled after Scratchbox login:
dh_make -e your.name@example.org --createorig
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 <enter> to confirm:
The dh_make command creates the debian/ directory containing configuration files. Many of them are templates, like a template for a man page, since Maemo does not ship applications with man pages due to space limitations, many of these files can be removed. The following table lists the files that are required:
| File in ./debian | Description |
|---|---|
changelog
| Package's change log |
compat
| Debian helper compatibily version. Leave it as it is. |
control
| Describes the packages to be made. |
copyright
| Copyright text. Fill in the blanks. |
rules
| A makefile containing the rules to build all kinds of packages such as, for example, source and binary. |
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 <your.name@example.org>
Build-Depends: debhelper (>= 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.
XSBC-Bugtracker: A link to a bugtracker location
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 XSBC-Bugtracker field contains a link to a bugtracker location. See the documentation on Maemo-specific fields for more information.
The XB-Maemo-Icon-26 field contains the application icon file (in this case, hello_icon_48x48.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.
uuencode can be installed from sharutils package:
[sbox-FREMANTLE_X86: ~] > fakeroot apt-get install sharutils
The following example encodes an icon file using uuencode inside Scratchbox:
[sbox-FREMANTLE_X86: ~] > uuencode -m icon.png icon.png > icon.png.en
In the above example, the result of the encoding is printed into a file named icon.png.en. 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/<SUBSECTION> syntax, where <SUBSECTION> 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 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] > 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 can be used to test the application in the SDK. When the source package is uploaded to the autobuilder, an Arm architecture-compatible .deb file will be built to distribute to Maemo devices and install using the Application Manager. You can switch to the FREMANTLE_ARMEL target in Scratchbox to test the build yourself and ensure that there is nothing PC-specific in it.
To test the package in the SDK, type:
[sbox-FREMANTLE_X86: ~/my-application-1.0.0] > cd .. [sbox-FREMANTLE_X86: ~] > 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 and How to make a package for the Hildon Application Manager.
 |
If the application is deploying icons to /usr/share/icons/hicolor, the gtk-update-icon-cache /usr/share/icons/hicolor command should be run in the postinst script to ensure that icons are displayed properly. |
[edit] Package Building
This section explains how to build software packages that the end user can install onto the Internet Tablet using the Application Manager tool in the device.
[edit] Prerequisites
This section assumes familiarity with the process of creating a .deb package. For more information on the basics of Debian packaging, see section Creating Debian Packages.
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
[edit] 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.
[edit] 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:
- Text formatting
- Software dependencies
- User sections
- Icons
- 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.
[edit] Text Formatting
All strings coming from the control information of a package are interpreted in UTF-8 when they are shown in the User Interface. If a string is not valid UTF-8, all bytes above 127 are replaced with '?' before display. If your control file is not UTF-8, you will fail a quality assurance test.
[edit] Dependencies
This field should now contain all the dependencies for package, such as ${shlibs:Depends}.
[edit] Sections
The Application Manager (AM) only displays packages in certain sections to the user in order to hide the hundreds of system packages making up the operating system. The AM is not designed to allow the user to manage the entire system at this point, only a 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/<SUBSECTION>
where SUBSECTION is one of the sections below:
| Key | Example English i18n | Example apps |
|---|---|---|
user/desktop
| Desktop | Home, statusbar and taskbar applets |
user/development
| Programming | py2deb |
user/education
| Education | Flashcard apps |
user/games
| Games | Doom, Duke Nukem 3D |
user/graphics
| Graphics | Photo apps, GIMP, Inkscape, fonts |
user/multimedia
| Multimedia or Sound & Video | Canola, mplayer, Kagu, UKMP, MediaBox |
user/navigation
| (Location &) Navigation | maemo-mapper, Navit |
user/network
| Internet & Networking | Web browsers, Samba clients, OpenAFS, Transmission |
user/office
| Office | GPE, Claws, AbiWord |
user/science
| Science | gnuplot, Octave |
user/system
| System | rotation-support, enhanced kernels, themes |
user/utilities
| Utilities or Accessories | Calculators, terminals, text editors |
Thus, if the package is wanted in the Office subsection, the field:
Section: user/office
should be included in the control information.
[edit] 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 48x48 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.
[edit] 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.
[edit] 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.
[edit] 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
[edit] Utilities to Use in Maintainer Scripts
[edit] 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.
[edit] 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.
[edit] 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 in the GKeyFile reference documentation. 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.
[edit] 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 > Application catalogues" dialog. Follow theGKeyFileconventions 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.
[edit] 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
[edit] 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 && apt-ftparchive packages . >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.
[edit] Signing Package
In order to sign packages, use debsign tool inside Scratchbox. For more information on using debsign, see the debsign manual page.
[edit] Deploying Packages
[edit] 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: ~] > 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.
[edit] 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.
[edit] Uploading Application Packaged to Extras
Debian packages can be distributed to end users with the Extras repository, which is pre-configured on the device. Before a package can be added to Extras, it must first be uploaded to Extras-devel, promoted to Extras-testing if QA checks succeed, and finally promoted to Extras after successful testing by community testers. The current Extras process is still under discussion, and may change in the future.
[edit] Red Pill Mode (This feature has been removed in the latest firmware)
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.
[edit] 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.
[edit] 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:
- Clean Apt Cache
Performs the equivalent of apt-get clean after every install or update. (This is the behavior for blue pill mode.)
- Assume Net Connection
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.
- Break Locks
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.
- Show Dependencies
Adds another tab to the details dialog with some dependencies from the package.
- Show All Packages
Does not filter out packages that are not in the "user" section. Also allows installing packages from any section.
- Show Magic System Package
Includes the "magic:sys" package in the list of packages. The effect of updating this package will resemble apt-get upgrade. Its exact behavior is not yet defined. This feature may become available in blue-pill mode in future.
- "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"
- This page was last modified on 18 June 2013, at 12:37.
- This page has been accessed 140,619 times.