Some Tricks for Writing PKG_File

1.    Some Useful Tricks For Writing PKG Files

This article explains some useful tricks that might be useful when creating installation package (PKG) files. It does not explain the format of PKG files. Please check SDK documentation for more information about PKG file. Most of the discussion below applies to Symbian OS 9 or newer only.

 

 

1.1    Displaying Localized Dialog

The PKG file allows us to display a dialog to the user during installation by specifying FILETEXT. For example:

 

"myfile.txt" - "", FILETEXT, TEXTABORT

 

This example displays a dialog in one language only. In some cases, you may also want to display localized dialog during installation to support more languages. This can be achieved by using an IF statement. For example:

 

IF (LANGUAGE=2)

   "myfile_02.txt"-"", FILETEXT, TEXTABORT

ELSEIF (LANGUAGE=3)

   "myfile_t03.txt"-"", FILETEXT, TEXTABORT

ELSE

   "myfile_t01.txt"-"", FILETEXT, TEXTABORT

ENDIF

 

The package file above displays text file depending on the device’s language. If the device’s language is set to French (02), then myfile_02.txt will be displayed; if German (03), myfile_03.txt will be displayed; otherwise myfile_01.txt will be displayed.

 

 

1.2    Installing Multiple Languages

There are two common ways of supporting multiple languages in the PKG file, i.e.:

 

• Install one language only. For example:

 

&EN,FR,GE

 

{

"/Epoc32/data/z/resource/apps/myapp.r01"

"/Epoc32/data/z/resource/apps/myapp.r02"

"/Epoc32/data/z/resource/apps/myapp.r03"

} - "!:/resource/apps/myapp.rsc"

During installation, the user will be prompted with the list of supported languages. For the above example, he will see three languages, i.e. UK English (01), French (02) and German (03). If the user selects UK English, then only myapp.r01 will be copied to the device and renamed to myapp.rsc. If the user selects French, then only myapp.r02 is installed.

 

Advantage: The user installs smaller number of files.
Disadvantage: If the user changes his device’s language, the application will be shown in different language.

 

• Install all languages. For example:

 

"/Epoc32/data/z/resource/apps/myapp.r01" - "!:/resource/apps/myapp.r01"

"/Epoc32/data/z/resource/apps/myapp.r02" - "!:/resource/apps/myapp.r02"

"/Epoc32/data/z/resource/apps/myapp.r03" - "!:/resource/apps/myapp.r03"

 

Using this approach, the user will not be asked which language to install. All supported languages will be installed to the device.

 

Advantage: If the user changes his device’s language; the application will be shown in the “right language”.
Disadvantage: The user installs files that may never be used at all. Besides that, installing many small files to the memory card takes much longer compared to phone memory.

 

 

1.3    Using Options List to Install Additional Languages

As explained in the previous section, you can either install files for all languages or one language only. There is another possibility to install several languages depending on user’s selection. The trick is by using options list. For example:

 

!({"English"}, {"French"}, {"German"})

 

IF option1

  "/epoc32/data/z/resource/apps/myapp.r01" - "!:/resource/apps/myapp.r01"

ENDIF

 

IF option2

  "/epoc32/data/z/resource/apps/myapp.r02" - "!:/resource/apps/myapp.r02"

ENDIF

 

IF option3

  "/epoc32/data/z/resource/apps/myapp.r03" - "!:/resource/apps/myapp.r03"

ENDIF

 

During installation, the user will be presented with a dialog containing three check boxes, i.e. “English”, “French” and “German”. He can then select the languages to install.

 

Note that you can also localize the options list. For example:

 

&EN,GE

 

!({"English", "Englisch"}, {"German", "Deutsch"})

 

 

Using this example, if the device’s language is set to UK English, the dialog will show “English” and “German”. If the device’s language is German, the dialog will show “Englisch” and “Deutsch”.

 

 

1.4    Installing Device-specific Files

In some cases, you may want to install a file that utilizes a feature available on certain device. However, you want all of them packaged into a single SIS file. It is possible to install device-specific files using IF statement.  For example:

 

IF MachineUid=0x2000060B ; Nokia N95

  "n95.dat" - "!:/private/12345678/myapp.dat"

ELSEIF MachineUid = 0x200005FB ; Nokia N73

  "n73.dat" - "/!:/private/12345678myapp.dat"

ELSE

  "generic.dat" - "!:/private/12345678/myapp.dat"

ENDIF

 

The package file above installs n95.dat if the device is Nokia N95; n73.dat if Nokia N73; otherwise it installs generic.dat.

 

The machine identifier (MachineUid) of each device can be enquired by HAL::Get(HalData::EMachineUid) method. There is also a table published by Forum Nokia containing machine identifier for S60 devices (see links section at the end of this article).

 

Furthermore, it is also possible display a dialog to the user if a device model is not supported. For example:

 

IF MachineUid=0x2000060B ; Nokia N95

  "notsupported.txt"-"", FILETEXT, TEXTABORT 

ELSE

  "myapp.dat" - "!:/private/12345678/myapp.dat"

ENDIF

 

The package file above displays a dialog containing notsupported.txt file if the user tries to install it on Nokia N95.

 

 

1.5    Supporting Limited Number of Devices

If you want to support some devices, you can specify the list of supported devices on the PKG file. For example:

 

[0x200005FB], 0, 0, 0, {"Nokia N73 ID"}

[0x200005F9], 0, 0, 0, {"Nokia N80 ID"}

[0x2000060B], 0, 0, 0, {"Nokia N95 ID"}

 

The package file above supports three devices only, i.e. Nokia N73, N80 and N95. If the user tried to install on other devices, he will get a warning saying that the application is not compatible. You don’t need to worry about localization in this case.

 

 

1.6    Checking File Existence

You can check the existence of a file using IF statement. It allows us to install a specific file by checking the existence of another file. It is useful, for example in the S60 platform. You can detect whether the device is S60 3^rd or S30 3^rd FP1 by checking the existence of z:/system/install/series60v3.1.sis. For example:

 

IF exists("z:/system/install/series60v3.1.sis")

  "myapp_31.dat" - "!:/private/12345678/myapp.dat"

ELSE

  "myapp_30.dat" - "!:/private/12345678/myapp.dat"

ENDIF

 

This example installs myapp_31.dat if the device is S60 3^rd FP1 and myapp_30.dat if the device is S60 3^rd.

 

Note that S60 3^rd FP1 devices have both series60v3.0.sis and series60v3.1.sis. Furthermore, S60 3^rd FP2 devices have series60v3.0.sis, series60v3.1.sis and series60v3.2.sis.

 

In means, you cannot use series60v3.0.sis to check whether the device is S60 3^rd because all FP1 and FP2 have this file as well.

 

 

1.7    Checking Package Existence

You can also check the existence of a package (SIS file). There might be some cases where you want to check whether a specific application or library has been installed. For example:

 

IF NOT (package(0x12345678))

  "myapp.dat" - "!:/private/12345678/myapp.dat"

ENDIF

 

This example checks whether package 0x12345678 has been installed on the device or not. If it has not been installed, then it will copy myapp.dat.

 

 

1.8    Links

• Official Package File Format documentation - http://www.symbian.com/Developer/techlib/v9.1docs/doc_source/N10356/Installing-ref/PKG_format/index.html
• S60 Platform Identification Codes - http://www.forum.nokia.com/info/sw.nokia.com/id/8731ef95-05d5-4596-844f-ebe326e16127/S60_Platform_Identification_Codes_v1_9_en.pdf.html