Packaging your application with Harmattan Platform SDK

In the Harmattan platform, applications are packaged according to the Debian policy. However, Harmattan enables you to use some additional metadata fields in the control file of the application. For a detailed description of the Harmattan-specific metadata fields, see Harmattan Appendix to the Debian Policy Manual. For information on the Debian policy, see the Debian New Maintainer's Guide.

The easiest way to create a Debian package is to use Debian's build helpers. When you create a project for the Harmattan target, MeeGo 1.2 Harmattan Platform SDK automatically sets up the following packaging files for the Debian package in the debian directory of your application:

copyright contains the information about copyright and license information.
compat contains the debhelper compatibility level.
README can be used to document any extra details or discrepancies between the original package and your Debian version.
rules contains the exact rules for different targets specifying how to the create the packages.
control includes the packaging metadata for your application.
changelog includes the package name, version, distribution, urgency, and changes made in the package revision.
manifest.aegis defines the credentials that your application needs to access protected Harmattan resources.

Packaging Harmattan applications before publishing in Nokia Store

To package your Harmattan application for publishing in Nokia Store:

Create a Debian package of your application.
Create a desktop file with the required information.
Add a launcher icon for your application.
Add a Package Manager icon for your application.
Edit the following files in the Debian package:
- In the README and README.debian files, update the information or remove the files if they are empty.
- In the copyright file, add copyright and license information for your application.
- In the control file, add the required descriptions for your application.
Add the localised metadata in the control and .desktop files of your application, if necessary.

Creating a Debian package

To package your Harmattan application for publishing in Nokia Store, package it as you would distribute it in a .tar.gz file. For example, when using autotools, this is done with make distcheck command.

Note: If you are using the c++-qml or meegotouch template included in the Harmattan target, you can proceed directly to step 9. For more information on the project templates, see Creating and running your first application with Harmattan Platform SDK.

To uncompress your package, enter the following command:

tar xfz <your_package_name>.tar.gz

The <your_package_name> directory is created.
Go to the <your_package_name> directory and enter the dh_make command.
To initialise the Debian package management file structure, enter the following command:

dh_make -e <your email address> -f ../<your_package_name>.tar.gz -c GPL

Note: You can, of course, choose a different license for your package.
Answer the resulting questions. In this case, you are packaging a single binary.
You can now edit the files in the debian/ directory which has been created to their desired values before packaging the software. You can delete many of the automatically generated files. All of the files ending in .ex or .EX are example files, intended to help you package different types of software. Usually you do not need to modify any files except debian/control.
Before creating a Debian package, set a changelog entry.

The .deb changelogs follow a special format, so be attentive when editing them. The changelog is an important file because it sets the version and revision of the source and binary packages. The file format is completely documented in the Debian New Maintainer's Guide.
To generate a Debian package from the source code, enter the following command:

dpkg-buildpackage -sa -rfakeroot -k<your email address>
The following files are created in the parent directory in which you unpacked the source code:
- <your_package_name>.orig.tar.gz
- <your_package_name>_i386.deb
- <your_package_name>.diff.gz
- <your_package_name>.dsc
- <your_package_name>_i386.changes
To change the target architecture to ARMEL, enter the following command:

sb-conf se HARMATTAN_ARMEL
Rebuild the package for ARM architecture to generate <your_package_name>_arm.deb. Enter the following command:

dpkg-buildpackage -sa -rfakeroot

Note: If sb-conf command fails because the current target is in use, you can change it with the sb-menu command.

Adding a desktop file

To allow the application to show up in the application launcher, it needs to have a desktop file in /usr/share/applications. You must add at least the following information in the desktop file:

Type: type of the item
- Application: item that starts an application
Name: name displayed for your application in the Applications view on the device
Exec: command to execute when you choose the item from the menu

For example:

[Desktop Entry]
Type=Application
Name=My calculator
Exec=/usr/bin/mygreatcalculator

For more information about the desktop files, see Desktop Entry Specification.

Adding application icons

There are two kinds of icons for an application:

The icon displayed in the Applications view of the Harmattan device.
The icon displayed by the Package Manager when the application is installed or removed, or an update is available for the application.

Adding an application launcher icon

To add an application launcher icon:

Create an icon that meets the following criteria:
- SVG format
- 80 x 80 pixels in size
Store the application icon in /usr/share/themes/base/meegotouch/icons/ .
Add a line to the application's desktop file that links to this icon file.

For example, the built-in Terminal application's icon is /usr/share/themes/base/meegotouch/icons/meego-terminal.svg. This means that the corresponding entry in the meego-terminal.desktop file is Icon=/usr/share/themes/base/meegotouch/icons/meego-terminal.svg.

Adding a Package Manager icon

To add a Package Manager icon:

Create an icon that meets the following criteria:
- PNG format
- between 26 x 26 and 64 x 64 pixels in size
  - 64 x 64 pixels is recommended.
- Reasonably minimal file size
To convert the PNG file into a base64 encoded format, enter the following command:

base64 icon.png > icon.txt
Add the contents of the converted file to the package's debian/control file under the XB-Maemo-Icon-26 section. For example:

[...]
Description: Terminal emulator for MeeGo.
XB-Maemo-Display-Name: MeeGo Terminal
XB-Maemo-Icon-26:
 iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABHNCSVQICAgI
 fAhkiAAAAAlwSFlzAAALEwAACxMBAJqcGAAAABl0RVh0U29mdHdhcmUAd3d3
[...]

Adding metadata in the control file

When publishing applications in Nokia Store, you must include certain metadata values in the package's debian/control file. The following table presents the mandatory packaging metadata.

**Mandatory metadata to add manually**
Field name	Accepted value	Description
Package	String that meets the following requirements: starts with an alphanumeric character. does not contain more than 100 characters includes only lower-case letters (a-z), digits (0-9), periods, plus (+) or minus (-) signs. does not contain underscores.	Package name Note: To make sure that the package name is unique in Nokia Store, it is recommended that you add a distinctive developer name or ID in the package name, such as a name or nickname of the developer or the company.
Version	#.#.# or #.# or #, where #= string {0-9}, <50 characters If you wish to publish your application in Nokia Store, do not use the debian revision in the version number.	Version number Note: If the content has already been tested and published in Nokia Store: You cannot decrease the major version. You can only decrease the minor version if you increase the major version. You can only decrease the patch version if you increase either the major or minor version.
Description	Free text	Description of the application. Add a short description of less than 60 characters on the first line after `Description` in the control file. If you want to provide more details on the package, start this description on the next line. You need to leave Column 1 of each line empty. Do not leave more than one blank line after the long description. Note: When adding a longer description for our application, you can use HTML-formatted Rich Text. This means that you can add links and tables to the description, if necessary. For more information on the supported HTML subset, see Qt documentation online.
XSBC-Maemo-Display-Name	One-line string	Name for the package displayed in the Package Manager UI instead of the value given in the `Package` field.
XB-Maemo-Icon-26	base64 coded icon	Icon to be shown by the Package Manager. When adding the text, you need to leave Column 1 of each line empty.

Localising metadata of your application

You can provide the following metadata of your Harmattan application in more than one language:

application description displayed by the Package Manager
application name displayed by the Package Manager
application name displayed in the launcher

The displayed metadata depends on the Harmattan device language settings. For example, if the selected language is Finnish, the metadata value with the Finnish language code is shown. If this does not exist, the default value is shown instead.

Note: In addition to the localised metadata fields in the control and desktop files, you must also include the default metadata that has not been localised.

Localising the description and name displayed in the Package Manager

Open the control file of your application.
To localise the name displayed for your application in the Package Manager, add a new line with the two-letter language code:

XSBC-Maemo-Display-Name-<uncapitalised language code>_<capitalised language code>: <localised name>
To localise the description of your application, add a new line with the two-letter language code:

XB-Description-<uncapitalised language code>_<capitalised language code>: <localised short description>
If you want to provide more details on the application in the target language, start this description on the next line. You need to leave Column 1 of the line empty.

Example of localised metadata values in the control file:

In this example, the short description and the name displayed in the Package Manager are provided in the default language (English) and Finnish.

Description: An application for storing your favourite photos.
XB-Description-fi_FI: Tällä sovelluksella voit tallentaa suosikkikuvasi.
XSBC-Maemo-Display-Name: Photo Album
XSBC-Maemo-Display-Name-fi_FI: Valokuva-albumi

Localising the name displayed in the launcher

Open the .desktop file of your application.
Add a new line with the two-letter language code:

Name[<language code>]=<localised application name>

Example of localised metadata values in the desktop file:

In this example, the name displayed in the launcher is provided in the default language (English) and Finnish.

Name=Photo Album
Name[fi]=Valokuva-albumi