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

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

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 [[:wikipedia:Advanced Packaging Tool|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|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 [http://www.isotton.com/software/debian/docs/repository-howto/repository-howto.html 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|Controlling Installation]].

== 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 <code>my-application-1.0.0</code>. The directory name should follow the <code><package-name>-<app-version></code> convention; in other words, the package that is being created for this application is called ''my-application''. See the [http://www.debian.org/doc/maint-guide/ch-first.en.html 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. <code>dh_make</code> command is available from debhelper package and should be enabled after Scratchbox login:
 dh_make -e your.name@example.org --createorig

Next <code>dh_make</code> 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 &lt;enter&gt; to confirm:

The <code>dh_make</code> command creates the <code>debian/</code> 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:

{| class="wikitable"
|+ Required files in <code>debian</code> directory
|-
! File in ./debian
! Description
|-
| <code>changelog</code>
| Package's change log
|-
| <code>compat</code>
| Debian helper compatibily version. Leave it as it is.
|-
| <code>control</code>
| Describes the packages to be made.
|-
| <code>copyright</code>
| Copyright text. Fill in the blanks.
|-
| <code>rules</code>
| A makefile containing the rules to build all kinds of packages such as, for example, source and binary.
|}

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

The following example illustrates what the <code>control</code> file for the example application must contain:

<pre>
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
</pre>

The <code>XSBC-Bugtracker</code> field contains a link to a bugtracker location. See [[Packaging#Maemo-specific_fields|the documentation on Maemo-specific fields]] for more information.

The <code>XB-Maemo-Icon-26</code> field contains the application icon file (in this case, <code>hello_icon_48x48.png</code>) encoded in base64. The Application Manager displays this icon next to the package name. To perform this encoding in Linux, use either <code>uuencode</code> or <code>openssl</code>; however, more suitable applications may also exist.

<code>uuencode</code> can be installed from sharutils package:

[sbox-FREMANTLE_X86: ~] > fakeroot apt-get install sharutils

The following example encodes an icon file using <code>uuencode</code> 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 <code>icon.png.en</code>. 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 <code>Section:</code> field in the control file must have the <code>Section: user/<SUBSECTION></code> syntax, where <code><SUBSECTION></code> 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 <code>rules</code> file. However, if the new .deb package is empty, check the "install:" section to make sure that the <code>DESTDIR</code> 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 <code>XB-Maemo-Icon-26</code>, but that is normal. The parent directory now contains a <code>my-application_1.0.0-0_i386.deb</code> 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 <code>FREMANTLE_ARMEL</code> 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 [http://www.us.debian.org/doc/maint-guide/ Debian New Maintainers' Guide]. For further information about creating application packages for maemo, see the next section [[#Making Application Packages|Making Application Packages]] and [http://hildon-app-mgr.garage.maemo.org/packaging-stable.html How to make a package for the Hildon Application Manager].

{{ambox
|text=If the application is deploying icons to <code>/usr/share/icons/hicolor</code>, the <code>gtk-update-icon-cache /usr/share/icons/hicolor</code> command should be run in the <code>postinst</code> script to ensure that icons are displayed properly.}}

== 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.

===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|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

===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:

* 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.

=== 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.

===Dependencies ===
This field should now contain all the dependencies for package, such as <code>${shlibs:Depends}</code>.

===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/&lt;SUBSECTION&gt;

where SUBSECTION is one of the sections below:

{| class="wikitable"
|+ Maemo package sections
|-
! Key
! Example English i18n
! Example apps
|-
| <code>user/desktop</code>
| Desktop
| Home, statusbar and taskbar applets
|-
| <code>user/development</code>
| Programming
| py2deb
|-
| <code>user/education</code>
| Education
| Flashcard apps
|-
| <code>user/games</code>
| Games
| Doom, Duke Nukem 3D
|-
| <code>user/graphics</code>
| Graphics
| Photo apps, GIMP, Inkscape, fonts
|-
| <code>user/multimedia</code>
| Multimedia ''or'' Sound & Video
| Canola, mplayer, Kagu, UKMP, MediaBox
|-
| <code>user/navigation</code>
| (Location &) Navigation
| maemo-mapper, Navit
|-
| <code>user/network</code>
| Internet & Networking
| Web browsers, Samba clients, OpenAFS, Transmission
|-
| <code>user/office</code>
| Office
| GPE, Claws, AbiWord
|-
| <code>user/science</code>
| Science
| gnuplot, Octave
|-
| <code>user/system</code>
| System
| rotation-support, enhanced kernels, themes
|-
| <code>user/utilities</code>
| 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.

===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 [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s5.7 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

===Utilities to Use in Maintainer Scripts ===

====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 [http://www.penguin-soft.com/penguin/man/1/debsign.html debsign manual page].

==Deploying Packages ==

===Installing Application Packages to SDK ===

Application packages can be installed into the Maemo SDK using the Debian package manager called <code>dpkg</code> 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.

===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.

===Uploading Application Packaged to Extras===

Debian packages can be distributed to end users with the [[Extras|Extras repository]], which is pre-configured on the device. Before a package can be added to Extras, it must first be [[Uploading to Extras-devel|uploaded to Extras-devel]], promoted to [[Extras-testing]] if QA checks succeed, and finally promoted to Extras after successful testing by community testers. The [[Extras repository process definition|current Extras process]] is still under discussion, and may change in the future.

=== 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.

==== 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:

* ''Clean Apt Cache''
Performs the equivalent of <code>apt-get clean</code> 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 <code>apt-get upgrade</code>. 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"

[[Category:Development]]
[[Category:Documentation]]
[[Category:Fremantle]]

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Templates used on this page:

Template:Ambox (view source) (semi-protected)

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Packaging,_Deploying_and_Distributing"

Personal tools

Navigation

Views

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

@@ Line 136: / Line 136: @@
 == 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.
 ===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|Creating Debian Packages]].
-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|Creating Debian Packages]].
+Use the "hello-world-app" example package to get started. To install it with apt-get, use the following command:
-Use the "hello-world-app" example package to get started. To install it with <code>apt-get</code>, 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 <code>apt-get</code> (namely <code>libapt-pkg</code>) in the standard way, without imposing any constraints; for example, packages are installed as root, and can touch the whole system.
+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 <code>apt-get</code> or dpkg are picked up by the Application Manager, and vice versa.
+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:
@@ Line 172: / Line 168: @@
 === 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.
 ===Dependencies ===
 This field should now contain all the dependencies for package, such as <code>${shlibs:Depends}</code>.
 ===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 <code>Section:</code> field in the control file should be in the following format:
+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>
+  Section: user/&lt;SUBSECTION&gt;
 where SUBSECTION is one of the sections below:
@@ Line 245: / Line 238: @@
 |}
-Thus, if the package is wanted in the Office subsection, the field:
- Section: user/office
+Thus, if the package is wanted in the Office subsection, the field Section: user/office should be included in the control information.
-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 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 <code>Maemo-Icon-26</code>.
+The image format of the icon can be anything understood by GdkPixbufLoader, but most commonly the PNG format is used.
-The image format of the icon can be anything understood by <code>GdkPixbufLoader</code>, but most commonly the PNG format is used.
 The image should be 48x48 pixels with a transparent background.
@@ Line 262: / Line 253: @@
 ===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.
@@ Line 274: / Line 264: @@
 === 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.
-When the Application Manager runs the maintainer scripts, they have no controlling terminal; their standard input is connected to <code>/dev/null</code>. The <code>DISPLAY</code> 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.
@@ Line 282: / Line 271: @@
 === 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 <code>maemo-application-running</code> utility.
+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 <code>PACKAGE</code>, the Application Manager runs the program named <code>/var/lib/hildon-application-manager/info/PACKAGE.checkrm</code>, 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.
+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:
@@ Line 293: / Line 281: @@
   foobarexampleonly.checkrm remove
-To upgrade, use the following, replacing <code>VERSION</code> with the version information:
+To upgrade, use the following, replacing VERSION with the version information:
   foobarexampleonly.checkrm upgrade VERSION
@@ Line 301: / Line 289: @@
 ====maemo-application-running====
- maemo-application-running -x executable-file
+   maemo-application-running -x executable-file
- maemo-application-running -d app.desktop
+   maemo-application-running -d app.desktop
-This utility is provided by the package <code>hildon-application-manager-dbg</code>. 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.
+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 <code>/proc/PID/exe</code>.
+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.
+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
+   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".
@@ Line 318: / Line 306: @@
 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 <code>postinst</code> script, ensure that even if the user does not agree to the licence terms, the <code>postinst</code> 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.
+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.
+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 <code>GKeyFile</code> format as described in the [http://library.gnome.org/devel/glib/unstable/glib-Key-value-file-parser.html#glib-Key-value-file-parser.description GKeyFile reference documentation]. A <code>GKeyFile</code> 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.
+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:
-<pre>
+ [catalogues]
-[catalogues]
+ catalogues = extras; sdk
-catalogues = extras; sdk
+ [extras]
-[extras]
+ name = maemo Extras catalogue
-name = maemo Extras catalogue
+ uri = http://repository.maemo.org/extras
-uri = http://repository.maemo.org/extras
+ components = free non-free
-components = free non-free
+ [sdk]
-[sdk]
+ name = maemo SDK catalogue
-name = maemo SDK catalogue
+ uri = http://repository.maemo.org/
-uri = http://repository.maemo.org/
+ components = free non-free
-components = free non-free
-</pre>
 A Group describing a catalogue can contain the following keys:
-* <code>name</code>: The display name of the catalogue as displayed to the user in the "Tool > Application catalogues" dialog. Follow the <code>GKeyFile</code> conventions to localize this key. If this key is omitted, the catalogue contains an empty name.
+* 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.
-* <code>uri</code>: 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.
+* 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.
-* <code>file_uri</code>: 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.
+* 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.
-* <code>dist</code>: 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.
+* 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.
-* <code>components</code>: 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.
+* 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.
-* <code>filter_dist</code>: Ignored if the distribution corresponding to the IT OS release on the device does not match.
+* 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 <code>uri</code>, <code>dist</code> and <code>components</code> fields are equal.
+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:
-In order to install packages with an .install file, the file must contain an "install" group. The group has one mandatory key, <code>package</code>, and one optional key, <code>catalogues</code>. The <code>catalogues</code> 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
-<pre>
-[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
-</pre>
 ==== 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".
-Installing packages from a memory card is governed by the <code>card_install</code> group. It has two mandatory keys, <code>packages</code> and <code>card_catalogues</code>, and one optional key, <code>permanent_catalogues</code>. The <code>packages</code> key lists the names of packages that can be installed from the memory card, using the <code>card_catalogues</code>. The package is installed in a temporary environment where the usual catalogues are not available. Only the catalogues listed by the <code>card_catalogues</code> key are configured. All of these catalogues must use <code>file_uri</code> instead of <code>uri</code>.
+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.
-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 <code>permanent_catalogues</code> 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:
-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 <code>card_install</code> group, of course. For example:
   $ mkdir .repo
   $ cp somewhere/*.deb .repo/
-  $ (cd .repo && apt-ftparchive packages . >Packages)
+  $ (cd .repo &amp;&amp; apt-ftparchive packages . &gt;Packages)
 A matching .install file could look like the following:
-<pre>
+ [card_install]
-[card_install]
+ card_catalogues = repo
-card_catalogues = repo
+ packages = app-1; app-2
-packages = app-1; app-2
+ [repo]
-[repo]
+ file_uri = .repo
-file_uri = .repo
+ dist = ./
-dist = ./
-</pre>
 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 [http://www.penguin-soft.com/penguin/man/1/debsign.html debsign manual page].