Home · All Classes · Grouped Classes · Annotated · Functions

Qpk Packages

Introduction

Qtopia uses a custom .qpk format for installable packages. Each .qpk file consists of program files organized in a specific directory structure that has been compressed.

It should be stressed that the qpk installation system was not meant to be a general purpose package installation system like ipkg. Packages installed with the qpk format have a number of limitations:

Package Project Elements

Typically there are 5 elements make up a package project

The project file describes the contents and configuration of a project. It typically specifies such things as where the source and headers come from, dependencies and the output file name, amongst a host of other options that the build system uses to build an application. Details on these options can be found at Qtopia Build System Documentation. A project file may be generated using

    $QPEDIR/bin/qtopiamake -project

A sample project file that can be found in the example application.

A package for an sxe-enabled phone will need a couple of special requirements to the source code and the project file.

The .desktop file is used to create an entry in the launcher for the application. The icon and user-visible name of the program is specified here. Note the Exec field of the .desktop file is assumed to refer to a binary in the bin directory of the package.

The structure of the package's directories in the final qpk file is generally automatically handled by the build system. There are various install hints that tell the build system what to do. Other sections of this documentation details how to make use of these install hints to make use of various resources and help files.

Quickstart

The tutorial for creating a new application may be used as quickstart example for building a package. The steps are exactly the same except that make packages should be used instead of make install. After the make packages step no further steps are required the qpk file will have been generated in a pkg subdirectory.

Creating and deploying packages

To make a package available for download and installation follow these steps:

  1. To build a package use the make packages command. This will create a pkg subdirectory containing the qpk package.
  2. Identify the directory your web server is serving from and create a feed directory there. The feed directory should by owned by the user who will publish packages.

    Note: For a default apache2 installation, content will be served from /srv/www/htdocs.

    You will likely need root privileges to create the feed directory and set the desired ownership. For example:

        sudo mkdir -p /srv/www/htdocs/feed
        sudo chown user.group /srv/www/htdocs/feed

    where user and group are the user name and group name of the user who will publish packages.

  3. Run the mkPackages script to genrate the packages.list file.
        sudo $QPEDIR/bin/mkPackages /srv/www/htdocs/feed

    From the current directory, this will recursively search for any packages and copy them into the feed directory /srv/www/htdocs/feed. A packages.list file will be created in the feed directory, listing all the packages found in it.

    If the feed directory is not supplied, the current directory is considered the feed directory and no recursive searching occurs. In this particular case one would do the following:

        sudo cp myappp.qpk /srv/www/htdocs/feed
        cd /srv/www/htdocs/feed
        sudo $QPEDIR/bin/mkPackages
  4. Set up the device to point to the package server feed. There are two ways to do this:
  5. Install package on to the device using Software Packages. The context menu of the Downloads tab allows the user to connect to a server. Once connected, the Software Packages application will communicate via HTTP with the server and download the packages.list file. It will then offer packages which are suitable for download. Any packages that don't match the device and/or version of Qtopia will not be presented for download. Packages that are already installed will be gray-ed out in the list.

Using the Resource System

To take advantage of the resource system, resources such as images and sounds should be installed into specific directories.

To register images, the pics install hint should be used in the project file. Be aware that the install task .path must be /pics/<appname> where <appname> refers to the application executable filename. Icons and images which depend on the language need to be placed in particular directories as outlined in the installpic Algorithm.

Assuming that there is a image called foobar.png and an icon called foobaricon.png, then the following code can be used to access those resources:

    QPixmap myPic(":image/foobar");
    QIcon myIcon(":icon/foobaricon");

The icon that associated with the application needs to be specified in a .desktop file. The Icon field should look something like:

    [DesktopEntry]
    ...
    Icon=<appname>/iconfile
    ...

To register sounds an install task should be specified like so:

    foo.files=sounds/*
    foo.path=/sounds/<appname>
    INSTALLS+=foo

Assuming that there is a sound called foobar.wav, then the following code can be used to access that sound:

    QSound mySound(":sound/foobar");

Using the Help System

To provide help information to users, the help install hint should be used. Bear in mind that the help files are placed in <helproot>/html or <helproot>/<lang>/html and not directly in the <helproot> directory.

At least one help file should be provided called <appname>.html where <appname> is the application binary name. This is the first help file that is presented to the user when the help option in the soft menu is invoked. Any other help files should be of the form <appname>-suffix.html eg. myapplication-howto.html.

As a side note, you may use QSoftMenuBar::menuFor() to generate a context menu which has a help option.

Internationalization

By default packages will be set to be internationalized to the same languages that Qtopia has been configured for. To modify which languages are targeted, the AVAILABLE_LANGUAGES and LANGUAGES variables in the .pro file can be modified to something similar to below:

    # Specify the languages that make lupdate should produce .ts files for
    AVAILABLE_LANGUAGES=en_US
    # Specify the langauges we want to install translations for
    LANGUAGES=$$AVAILABLE_LANGUAGES

To generate an initial set of .ts files, in the package source directory run

    make lupdate

The .ts files can then be used in conjunction with linguist to generate the translations. Running make packages, will create a qpk file with the .qm files appropriately placed in the qpk's package directory structure.

See Also Internationalization

Settings Files

Any settings files used by the package should not correspond with any organizations listed under the RestrictedOrganizations parameter in the PackageManager.conf file. On an SXE configured Qtopia, packages won't have write access to these settings files and so should use other organizations to avoid any problems. For similar reasons, packages should use QSettings objects at user scope.

Creating a settings file using QSettings will automatically (on both SXE and non-SXE enabled devices) place the settings files in the package sandbox directory.

Pre-generated settings files that should be placed in the Settings directory in a similar manner to that shown below:

    foo.files=mysettings/*
    foo.path=/Settings/
    INSTALLS+=foo

where the configuration files have been positioned as follows:

organizationapplicationlocation
foobarmysettings/foo/bar.conf
foononemysettings/foo.conf

A package that contains a settings file whose organization is in the RestrictedOrganizations list will not be installable.

Troubleshooting package installation

If there are issues that occur during package installation, the Package Manager/Software Installer will show up a simple dialog mentioning that the package could not be installed but provide very little detail. Details of why the package did not install are presented in the Qtopia log/console output.

For extra information, turn on Package Management logging either via the Settings->Logging application or by editing the Log.conf file and then restart qtopia. The log output will provide more detailed information on what is happening during package installation.

The logging out put can be viewed in a number of ways

FAQ

Q: My packages are in the feed directory but why I can't see them with Software Packages?

A: Ensure that you have re-generated the packages.list file with mkPackages. Also ensure that the package is compatible with the version of Qtopia on the device and the device itself, otherwise they will not be visible and cannot be installed. Turning on Package Management logging will give more details.

Q: I have a package from Qtopia version x but i want to use it on Qtopia version y but I can't because x and y are not binary compatible.

A: If you want to try a package that is not compatible with the version of Qtopia on the device you can use the modqpk script to modify the package's QtopiaVersion field. QtopiaVersion consists of a comma delimited list of versions which can include ranges eg, 4.1,4.2.0-4.2.4. Generally, it is not recommended that this be done.

Q: I've made a qpk package for the desktop and am running Qtopia with qvfb and it works fine, but when I try the same qpk on another desktop machine, the package doesn't run.

A: The runtime library path is hardcoded into the package executable at compile time. On a device this isn't a problem since all the devices will have the same file system structure. For the desktop, the situation is different since on one machine the path may be /home/bob/Qtopia/lib while on another it's /home/bert/Qtopia/lib; a workaround may be to modify the LD_LIBRARY_PATH or just recompile the package for the other machine.

Q: I made a package called Bloxx and have installed it on my device. Someone else has also made a package co-incidentally called Bloxx, when I try to download their package from their server the package manager says it's already installed.

A: Two packages of the same name cannot be installed at the same time; if two packages have the same name and same icon, the user cannot distinguish between them in the application launcher. Packages that share the same md5sum are also considered to be the same package.

Q: I have a desktop file that refers to a binary which is in the package's etc directory. The package does not install because it says the desktop file does not reference a binary.

A: All desktop files can only reference binaries that get placed in the package's bin directory. Also the desktop file must actually reference a binary and not a symlink in the bin directory. Be aware that the bin directory itself must not be a symlink. If these conditions are not met, installation of the package will be prevented. Most of the time the build system automatically handles placement of executables in the bin directory, the developer usually does not have to concern him/herself with this.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3