The K-Zone: My first Qtopia application -- how to get started with Qtopia development -- part 5

Packaging the application

In this section I will explain how to package the simple application into an ipk file for distribution.

Structure of an ipk file

An ipk file is a compressed archive containing three things (each of which can in turn contain other things)...

A file called debian-binary which identifies this ipk to the installer. It contains a single line of text.
A file called data.tar.gz, which contains the executable, configuration files, icons, data, etc. This is where all the action is.
A file called control.tar.gz which contains a description of the application, along with any pre-installation and post-installation shell scripts that are required to configure it.

Creating and compressing the control file

This bit, at least, is easy. Create a file like this, and call it control. This name is not configurable -- the file must be called control, or it won't work.

package: pma_test
Installed-Size: 24000
Filename: ./pma_test.ipk
Version: 0.01
Depends:
Priority: optional
Section: qpe/utilities
Maintainer: your name here 
Architecture: arm
Description: Test application

It should be fairly obvious what most of these entries mean. Installed-Size does not have to be exact -- it is just to warn the user what to expect. The `Depends:' entry is a list of all the other packages which must be installed in order for this one to work. In this case, there are no dependencies, so this field is empty.

Compress this file into control.tar.gz as follows:

tar cvfz control.tar.gz ./control

If you are familar with Unix, your intuition might tell you that you don't need the ./ in front of control. Your intuition, in this case, would be wrong. If you don't include the dot-forward-slash, it won't work. The Qtopia installer checks for the dot, at least on the PMA430. Trust me on this -- I've found out the hard way.

Creating and compressing the application

This bit is slightly more tricky -- you have to create an archive that will expand in such a way that all the bits drop neatly into the right place in subdirectories of /opt/Qtopia (or one of its counterparts -- remember the first section of this article). You will need at least three things in this archive:

The executable (which we wrote and tested earlier)
A .desktop file (to tell the launcher what to do)
An icon (to, er..., be an icon)

Lets start by creating the directory structure for the archive. Do this in an empty directory.

mkdir -p opt/QtPalmtop/bin
mkdir -p opt/QtPalmtop/apps/Applications
mkdir -p opt/QtPalmtop/pics

The three directories so created will contain the executable, the .desktop file, and the icon respectively. Again, you have no discretion in the names of these directories: the names reference directories that already exist on the PMA430, so if you change any names you'll end up with stuff in the wrong place. The installation will still succeed, but you'll end up with an application that can't be run.

Now copy the executable you compiled in the previous section into opt/QtPalmtop/bin.

The next step is to create the .desktop file. Again, there isn't space here to describe all the elements that could go in this file, but a simple example is self-explanatory.

[Desktop Entry]
Comment=PMA430 test app
Exec=hello3
Icon=hello3
Type=Application
Name=Test app

The entry Exec=hello3 tells the launcher to run the application hello3, which it will expect to find in the bin directory. Icon=hello3 tells the launcher to display the icon hello3.png, which is expected to be in the pics directory. Note that icons must be .png files, of size 32x32 pixels. On Linux, gimp is a good tool for creating icons, but there are, no doubt, others. If you can't be bothered to create an icon for this exercise, borrow one from the Qtopia directory (e.g., /opt/Qtopia/pics/inline/datebook_icon.png).
You need to copy the icon file, whch must be named hello3.png into ./opt/QtPalmtop/pics, and the .desktop file, which can be called anything so long as it doesn't clash with any other application (let's call it hello3.desktop) into

./opt/QtPalmtop/apps/Applications
At the end of this sequence of operations, you need to end up with a
directory structure like this:

opt
  QtPalmtop
    pics
      hello3.png
    apps
      Applications
        hello3.desktop
    bin
      hello3


Now we can compress this directory structure into data.tar.gz.
Again, this name is not discretionary -- the Qtopia installer will choke
if it doesn't find a file with this name.

tar cfvz data.tar.gz ./opt


Creating the ipk file

Now we can create the installable package from the files created
in the previous steps.


     

First create the file debian-binary. It should contain
exactly one line of text:

2.0


Now we can compress the whole thing up to make the installable
package.

tar cvfz hello3.ipk ./data.tar.gz ./control.tar.gz ./debian-binary


Again, the ./ in front of each filename is
important. If you leave this out, the installation will fail.


You now have an installable package which you can test. Copy
the .ipk file into the Documents directory of the PMA430, and
start the `Package manager' application from the Settings tab.
Fingers crossed... You should get a new icon in the Applications
tab, and you should be able to run the application from that
icon.

Go to part 6...







©1994-2006 Kevin Boone, all rights reserved