MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Packaging your application

In the MeeGo 1.2 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.

When you create a project for the Harmattan target, Qt Creator automatically sets up the required packaging files for the Debian package in the qtc_packaging directory of your application. Qt Creator then asks if you want to add the packages to your project. Select Yes to add the packaging files to your project. For more detailed information on the Debian packaging files, see Anatomy of an application.

Packaging Harmattan applications before publishing in Nokia Store

To package your Harmattan application for publishing in Nokia Store:

  1. Build or run your project in Qt Creator. For instructions on this, see Running the application.
  2. Replace the default Qt application icon in the project folder with your own launcher icon. The recommended format for the icon is .PNG, and the recommended size is 80 x 80 pixels.
    This icon will be displayed for your application in the application launcher (at run time in the Applications view of the Home screen).
  3. Add the application name in the desktop file of your application.
    This name will be displayed for your application in the Applications view.
  4. Add the mandatory and optional packaging metadata in the control file your application.
  5. Edit the aegis manifest file manually, if:
    • your application provides protected services to other applications.
    • you have problems with the automatically generated file.
    For information on editing the manifest file manually, see Creating a manifest file manually and Security guide.
    Certain Harmattan APIs and Qt Declarative modules always require a security token. For more information, see Harmattan APIs that require security credentials.
  6. Add the copyright information for your application.
  7. Add localised metadata in the control and .desktop files of your application, if necessary.

Modifying desktop file in Qt Creator

To set the name displayed for your application in the Applications view, you must modify the desktop file for your application:

  1. In Qt Creator, select the Edit mode.
  2. Highlight the main directory of your application (the topmost in the tree view).
  3. Switch the Projects view to the File System view from the drop-down menu above the project tree view.
  4. Double-click your application's desktop file, it is named <project name>_harmattan.desktop.
    Note: Desktop files for Harmattan applications are named <project name>_harmattan.desktop, and desktop files for Fremantle applications are named <project name>.desktop.
  5. In the desktop file, the default Name value is the name of the project. Modify the Name value in the desktop file:
    Name=<name displayed in the Applications view>
  6. Go to the File menu and select Save "<file name>".

For more information on the .desktop file format, see Desktop Entry Specification.

Modifying control file in Qt Creator

If you want to publish your application in Nokia Store, you must give your application the following metadata:

  • package name
  • package version
  • package description
  • name and icon to be displayed in Package Manager (during the installation)

When you edit these files in Qt Creator UI, they are automatically updated in the control file of your application. To modify the package metadata for your application in Qt Creator:

  1. Switch to Projects mode button.
  2. On the target toolbar above Run Settings/Build Settings, select Harmattan > Run to configure Run settings.
    File:Nokia_Qt_SDK_target_bar.png.
  3. Click Details on the Create Package line.
  4. In Package name field, modify the name given for the Debian package. To make sure that the package name is unique in Nokia Store, it is recommended that you add a distinctive developer name or ID to the package name, such as a name or nickname of the developer or the company.
    This package name is used for your application in Nokia Store. Make sure that the package name:
    • starts with an alphanumeric character.
    • does not contain more than 100 characters.
    • only includes lower-case letters (a-z), digits (0-9), periods, plus (+) or minus (-) signs.
    • does not contain underscores.
    Note: If the package name does not meet the above requirements, your application cannot be published in Nokia Store.
  5. In the Package version drop-down menu, select the version number for your application. The first version of the application submitted to Nokia Store starts from 1.0.0. 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.
    Note: If you want to submit an update that is not free, add a new package name for your application. If you only raise the version number, the content item is available for free through Nokia Store if a previous version has already been purchased.
  6. In the Short package description field, add a clear description of your application. For example: An application for storing your favourite photos.
    Note: You can add a longer description for your application in the Description metadata field in the control file. For instructions on editing the control file, see Modifying optional metadata fields in the control file.
  7. In the Name to be displayed in Package Manager field, add a display name that is shown for your application in the Package Manager during the installation. If you do not specify any value here, the value given in the Package name field will be shown.
  8. To add an application icon that is shown in the Package Manager for your application, click the Icon to be displayed in Package Manager button and choose the image file. The icon file must meet the following criteria:
  • The icon must be a PNG file. You can create the icon with any software that can create PNG files. For example you can use Paint.NET for Microsoft Windows, GIMP for Linux and Seashore for Mac OS X.
  • The maximum dimensions for the icon are 64 x 64 pixels, which is the recommended native size. The minimum dimensions for the icon are 26 x 26 pixels.
  • It is recommended to keep the file size to a minimum with suitable compression and colour settings. Qt Creator automatically encodes the PNG file to a base64 format.

The following figure illustrates the displayed settings. In this example, the created package has been named photoalbum.

Modifying run settings

Modifying optional metadata fields in the control file

To modify the control file in the text editor of Qt Creator:

Note: If you edit the control file manually, make sure that the text is encoded in UTF-8. For more information on the syntax of control files, see Debian Policy Manual.

  1. Switch to Projects mode button.
  2. On the target toolbar above Run Settings/Build Settings, select Harmattan > Run to configure Run settings.
    File:Nokia_Qt_SDK_target_bar.png.
  3. Click Details on the Create Package line.
  4. To open the control file, select control from the Adapt Debian file drop-down menu and click Edit.
    The file opens in the text editor of Qt Creator.
  5. Make the required changes.
  6. Go to the File menu and select Save "<file name>".
    Note: When adding a longer description for your 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.

Modifying copyright file in Qt Creator

Before submitting your application to Nokia Store, modify the copyright file in the text editor of Qt Creator:

  1. Switch to Projects mode button.
  2. On the target toolbar above Run Settings/Build Settings, select Harmattan > Run to configure Run settings.
    File:Nokia_Qt_SDK_target_bar.png.
  3. Click Details on the Create Package line.
  4. To open the copyright file, select copyright from the Adapt Debian file drop-down menu and click Edit.
    The file opens in the text editor of Qt Creator.
  5. Make the required changes.
  6. Go to the File menu and select Save "<file name>".

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 Applications view

The displayed metadata depends on the Harmattan device language settings. For instance, 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

  1. Switch to Projects mode button.
  2. On the target toolbar above Run Settings/Build Settings, select Harmattan > Run to configure Run settings.
    File:Nokia_Qt_SDK_target_bar.png.
  3. Click Details on the Create Package line.
  4. To open the control file, select control from the Adapt Debian file drop-down menu and click Edit.
    The file opens in the text editor of Qt Creator.
  5. 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>
  6. 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>
  7. 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.
  8. Go to the File menu and select Save "<file name>".

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 Applications view

  1. In Qt Creator, select the Edit mode.
  2. Highlight the main directory of your application (the topmost in the tree view).
  3. Switch the Projects view to the File System view from the drop-down menu above the project tree view.
  4. Double-click your application's desktop file, it is named <project name>_harmattan.desktop.
  5. Add a new line with the two-letter language code:
    Name[<language code>]=<localised application name>
  6. Go to the File menu and select Save "<file name>".

Example of localised metadata values in the desktop file:

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

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