Package file format .pkg

A pkg file is a text file which contains installation information for applications or files. It consists of the following parts, some of which may be omitted:

• the languages supported

• the package header, including the name of the component to be installed and its build and version information

• product / platform version compatibility (where implemented)

• package-signature details (optional)

• package-lines (optional) formed from the following:

• options line

• condition blocks

• language independent files to install

• language-dependent files, of which only one will be installed

• capabilities line

• requisite components

• embedded SIS files

• comments

The first item in the pkg file should detail the languages provided within the sis file followed by the package header which details the name of the component to be installed in all supported languages, the UID of the component, and version information. An optional digital signature line may be specified which gives the name of the private key file and associated certificates to be used to digitally sign the sis file. The remainder of the file lists the files and components to be included in the sis file or dependencies upon other installed components.

• With respect to v5, arguments in pkg files no longer have to be abbreviated — longer variants of the same options are supported, e.g. FILETEXT rather than "FT".

• All pkg files parsed by the Installation File Generator may be in either UTF8 or Unicode format. UTF8 text is converted to Unicode when creating a sis file. Both little-endian and big-endian Unicode files may be used; automatic conversion is performed by the Installation File Generator as appropriate.

• Characters may be included within strings using an escape syntax. The following samples demonstrate the use of a character code to include a "™" symbol at the end of the application name:

"MyApp<153>"

"MyApp<0x99>"

• Numeric character codes should be entered outside double quotes and bounded by "<" and ">". The value may be in the range 0-65535.

• A single PKG command line may be spread over multiple lines if desired, it does not all have to appear on a single line.

The language line specifies which languages are supported by the component. Languages are identified by a two character code. The line may be omitted; if so, UK English is assumed by default. The language line must be specified before any other section. Its format is as follows:

&Language_1,..., Language_n

For example:

&EN,FR,IT

The following languages are supported:

EN UK English SG Swiss German FR French PO Portuguese GE German TU Turkish SP Spanish IC Icelandic IT Italian RU Russian SW Swedish HU Hungarian DA Danish DU Dutch NO Norwegian BL Belgian Flemish FI Finnish AU Australian English AM US English BF Belgian French SF Swiss French AS Austrian German IF International French NZ New Zealand CS Czech SK Slovak PL Polish SL Slovenian TC Taiwan Chinese HK Hong Kong Chinese ZH Prc Chinese JA Japanese TH Thai

The number of text strings in the following line types should match the number of languages specified in the languages line and be in the same order:

• package header

• option lines

• language dependent files

• requisites

The package header must be included before all other items, except the language line, if one is specified. Its format is:

#{"Component Name for language1", "Component Name for language n"},(ComponentUID),Major,Minor,Build-Number[,Package Options] [,TYPE=Package Type]

The package header contains the component name in each of the supported languages, the UID of the component, the major and minor version number and build number, and package options.

For example:

#{"MyApp"},(0x10000001),1,0,0,TYPE=SISAPP

• All sis files require a UID, even if the installed files do not require one.

• The application's major and minor version numbers are required for version control (eg. AppName 3.1 specifies a major build 3, and minor build 1.)

• The build-number replaces the variant value which was unimplemented in v5 and previous versions of the Installation File Generator.

• All numbers can be hexadecimal.

• The component name is language dependent. It is used to identify the component in the installation dialogs and in the list of installed programs in the control panel's Add\remove program.

• The number of component names must equal the number of languages specified in the languages line, and should be in the same order.

One or both of the following package options can be specified:

Abbrev. option Full option name SH SHUTDOWNAPPS NC NOCOMPRESS

The package type allows the user to easily identify the main installed applications, distinct from any system components. They also let the add/remove control panel item distinguish the packages which the user may not remove. For example, installing an application is installed using the SYSAPP type: #{"MyApp"},(0X100000001),1,0,0,SH,NC,TYPE=SYSAPP

The package type may be followed with only one of the package type arguments;

Abbrev. option Full option name Description SA SISAPP Contains an application (the default type). SY SISSYSTEM Contains a shared/system component such as a DLL or OPX which may be used by a number of applications. The component will be removed when the last application is removed which uses it. SO SISOPTION Contains an add-on or optional component, (dynamically loaded code, data files,…). The user may choose whether to install the component and may later remove the component independent of the main application it works with. SC SISCONFIG Configures an existing application or service. The package should not contain any new files, only files which are either run or displayed during installation, or added to an existing component, e.g. settings. The package will not appear as a removable component after installation. SP SISPATCH Patches an existing component. It may be removed by the user. SU SISUPGRADE Upgrades an existing component. The package is not listed as a removable component after installation, the user will need to remove or reinstall the associated application to remove the changes.

• The ID and I8 (non-Unicode sis files) flags have been dropped from post v5 releases

• The UID value should be unique for the following types of sis file: Applications (SISAPP), System/shared components (SISSYSTEM), Add-on/optional components (SISOPTION).

• The UID for the following types of SIS files should be identical to the UID for the main app or system component with which they are associated: Configuration components (SISCONFIG), Patches (SISPATCH), Upgrade components (SISUPGRADE).

Note: This feature may not be supported by all Symbian OS platforms. See your product-specific SDK to find out whether it is supported, and if so, which UIDs, feature identification string and version numbers to use.

Each product is assigned a unique ID which is used by the application installation mechanism to ensure that only compatible applications can be installed on the phone.

Also, each platform version is assigned a unique ID. It is assumed that a platform version is compatible with all earlier platform versions, but not with any later versions.

An installation package must declare the UID of the product, or platform version that it is designed to be installed on. The UID should identify the earliest possible platform version or product to maximise the number of phones the package can be installed on.

To specify which product / platform version the installation package is compatible with, add the following line to the .pkg file:

(0x12345678), 0, 0, 0, {"ProductID"}

where:

• (0x12345678) is the UID of the product/platform version.

• 0, 0, 0, are major version, minor version and build numbers.

• {"ProductID"} is the feature identification string.

The package signature line is used when creating a digitally signed installation file. The signature will be checked when the package is installed and details of the certificate will be available to the user at install time and when listing installed components. The signature line format is:

*private-key-file,public-key-cert[,KEY=privatekey-password]

• The private-key-file refers to the name of a private key file used to create a digital signature. The private key is used only when creating the sis file, the name of the file is not embedded within the resultant sis file. If no package-signature line appears in the pkg file the package will be unsigned.

The optional KEY parameter specifies the password used to access the private key file if it has been encrypted. If the key is encrypted, but the KEY parameter has not been specified then the Installation File Generator will prompt the user for the access password

• The public-key-cert refers to a single file containing either the corresponding public key certificate (.cer file) or a certificate chain file (.p7c) containing the corresponding public key certificate and its associated certificates (necessary to form a certificate chain to a trusted root certificate).

Certification Generator syntax makekeys.exe

Condition blocks may be used to control the installer according to various attributes. The syntax is as follows:

IF condition package-lines [ ELSEIF condition package-lines ] [ ELSE package-lines ] ENDIF

For example, two sets of files may be included within the install package, one set for an ARM processor and one set for an M-CORE processor. An IF/ELSEIF block may be used with the CPU-type attribute to ensure the correct files are installed on the target phone.

For example:

IF cpu=0 ; ARM
 "marm\myapp.app"-"!:\System\Apps\MyApp\Myapp.app"
ELSEIF cpu=1 ; MCORE
"mcore\myapp.app"-"!:\System\Apps\MyApp\Myapp.app"
ELSE
 ; unsupported cpu type, display a message & exit!
 "nosupport.txt"-"", FILETEXT, TEXTEXIT
ENDIF

• Most pkg lines are valid within a condition block, however the following line types may not be used: languages, package-header, package signature, requisites, capabilities.

• The use of an IF…ELSE construct and conditions allows a single installation file to support any number of different devices.

condition-primitive (condition) AND (condition) (condition) OR (condition) NOT(condition)

attrib=value attrib<>value attrib>value attrib<value attrib>=value attrib<=value exists(filename) appcap(uid,capid) devcap(capid)

• The exists() function may be used to test for the existence of a given file. The devcap() and appcap() functions may be used to test for device and application capabilites.

Attributes Value Manufacturer 0=Ericsson, 1=Motorola, 2=Nokia, 3=Panasonic, 4=Psion 5=Intel 6=Cogent 7=Cirrus 8=… ManufacturerHardwareRev Manufacturer-specific: 0x100=1.00 etc ManufacturerSoftwareRev Manufacturer-specific: 0x100=1.00 etc ManufacturerSoftwareBuild Manufacturer-specific: 257 etc MachineUID Device specific values for products (see epoc32\include\hal_data.h): EMachineUid_Series5mx=0x1000118a, EMachineUid_Brutus=0x10005f60, EMachineUid_Cogent=0x10005f61, EMachineUid_Win32Emulator=0x10005f62, EMachineUid_WinC=0x10005f63, EMachineUid_CL7211_Eval=0x1000604f DeviceFamily 0=Crystal, 1=Pearl, 2=Quartz DeviceFamilyRev 0x600=6.0, 0x610=6.1 etc CPU 0=ARM, 1=MCORE, 2=x86 CPUArch 0x400=ARM4, 0x410=ARM4T, 0x500=ARM5, 0x300=M340, ???=x86 CPUABI 0=ARM4, 1=ARMI, 2=THUMB, 3=MCORE, 4=MSVC CPUSpeed CPU clock speed/1024: eg 36864=36MHz SystemTickPeriod Tick period in microseconds SystemSpeed Approximate speed relative to Series5=100 MemoryRAM eg 0x800000 MemoryROM eg 0xC00000 MemoryPageSize eg 0x1000 PowerBackup 0=none, 1=supported Keyboard 0=none, or bitmask of: 1=EKeyboard_Keypad, 2=EKeyboard_Full KeyboardDeviceKeys Number of device-specific keys: eg 5 KeyboardAppKeys Number of application keys: eg 8 KeyboardClick 0=none, 1=supported KeyboardClickVolumeMax eg 1 DisplayXPixels eg 640 DisplayYPixels eg 200 DisplayXTwips eg 3200 DisplayYTwips eg 1440 DisplayColors 2, 4, 16, 256, 65535 etc DisplayContrastMax eg 37 Backlight 0=none, 1=supported Pen 0=none, 1=supported PenX eg 695 PenY eg 280 PenDisplayOn 0=no, 1=yes PenClick 0=none, 1=supported PenClickVolumeMax eg 1 Mouse 0=none, 1=supported MouseX eg 640 MouseY eg 200 MouseButtons eg 2 CaseSwitch 0=none, 1=supported LEDs eg 2 IntegratedPhone 0=none, 1=supported NumHalAttributes Number of supported HAL attributes Language Machine language RemoteInstall 0=Symbian OS based install, 1=installation via a PC Option<n> 0=option not selected, 1=option selected

Option<n> attributes behave as global variables, which is significant if there is an options line both in a main sis file and an embedded sis file.

Option lines are used to display a list of options to the user. The option required is selected and will usually control the installation of optional components later on in the .sis file. The syntax of the options line is as follows:

!({“Option1 string language 1”,…, “Option1 string language n }, …,{“Option m string language1”,…, “Option m string language n”})

For example:

!({"Add-on 1 (20KB)"},{"Add-on 2 (75KB)"}, {"Add-on 3 (80KB)"},{"Add-on 4 (20KB)"})

Selection affects the values of special built-in attributes (option1, option2, option3,…). If option 1 is selected then the value of the option1 attribute will be 1, otherwise it would be 0. Condition-block statements that follow the option-line may test and act upon these selections. For example:

IF option1
 "addon1.opo"-"!:\System\Apps\MyApp\addon1.opo"
ENDIF

Ideally these lines should appear towards the start of the pkg file so that the user is prompted at the start of installation, however this is not required and the options may be displayed at any point in the installation

Files which will be installed regardless of the language variant selected by the end user, are specified as follows;

"Source"-"Destination"[,Arguments]

For example:

"examples\ToolsAndUtilities\Install\HelloWorld.app"-"!:\system\apps\HelloWorld\HelloWorld.app"

The source is the path and filename for the source file on the PC. The destination is the target path and filename on the phone. A destination must be specified unless the file is a text file displayed at install time. Text files are not installed, so their destination is irrelevant, and may consist of empty quotes.

A “!” character may be used in place of the drive letter if the user is to be given the choice of the drive to install the file to.

Applications must be installed to \system\apps\appname\appname.app. Other component files which form part of the application, for example resource files and application information files, should reside in the same directory as the application. If the \appname\ directory does not exist, it will be created.

Files are installed in the order in which they are specified in the pkg file.

If the file is used by other components, e.g. if it is a shared DLL for instance, you may want to avoid the possibility of it being overwritten by an earlier version. In this case, do not specify the file in this section. Instead, create a separate sis file for the shared file, including appropriate major, minor build numbers in the package header, and include the new sis file in the sis Component Files section.

An optional comma-separated list of arguments following the destination file may be specified, to describe the type of file and how it will affect the installation or removal process.

Use one of the following arguments to describe the type of file to install:

FF FILE Standard file. This is the default. FT FILETEXT A text file whose contents will be displayed in a dialog box during installation. The dialog will display either the default Continue button, or Yes and No buttons, depending on other arguments specified. Text files are not installed on the target machine. FN FILENULL A file which does not yet exist, so is not included in the sis file. It is created by the running application and will be deleted when the application is removed. The name assigned to the source file is unimportant and should be empty, i.e. “”. Note that such files will not be deleted when upgrading to a later version. This ensures that such files as .ini files, which store application preferences, are not lost in an upgrade. FM FILEMIME A file which instructs the installer to pass the given file to the default application associated with the given mime type, e.g. text/x-vCard for contact details. See WSPContentTypes for further MIME types. The MIME type, in quotes should be specified after the FM argument, for example: "mypicture.gif"-"!:\system\apps\myapp\mypicture.gif", FM, "image/gif" FR FILERUN A file which will be installed on the phone, and run during installation and/or removal — depending on arguments RI, RR, RB described later. The file could be an executable, a document or an application.

• Text files displayed during install (using the FT option) should be in UTF8 or Unicode format and will be converted by the Installation File Generator to the correct format, i.e. Unicode.

• Note that where installation is controlled from a connected PC, and FR or FM options are used, the application will be started on the target phone not the PC and therefore if the application displays anything, it will be on the target phone, not the PC.

Use one of the following arguments for a text file, i.e. after FT has been specified, to determine how the text file dialog should be cancelled, and how cancellation should affect the installation:

TC TEXTCONTINUE Use a Continue button in the text file dialog. When the user presses this button the dialog is cancelled and the installation continues. This is the default. TS TEXTSKIP Use Yes and No buttons in the text file dialog. If Yes is pressed, the dialog is cancelled and the installation continues. If No is pressed, the dialog is cancelled, and the installation will continue, but the next file or component specified in the pkg file will not be installed. TE TEXTEXIT Use Yes and No buttons in the text file dialog. If Yes is pressed, the dialog is cancelled and the installation continues. If No is pressed, the installation is aborted and any installed files are removed. TA TEXTABORT Use Yes and No buttons in the text file dialog. If Yes is pressed, the dialog is cancelled and the installation continues. If No is pressed, the installation is aborted — normally resulting in a partial installation.

One of the following arguments may be specified for a file which will be run during the installation or removal process, i.e. after FR has been specified. If the file is a document, the appropriate application will be launched. For example, on installation, you may want to open a document providing information about the new application.

RI RUNINSTALL Run the file during installation only. This is the default. RR RUNREMOVE Run the file during removal only. RB RUNBOTH Run the file during both installation and removal.

Use one of the following arguments after RI, RR or RB has been specified.

RE RUNSENDEND Indicates that the installer should send a shutdown message to the started program in order to shut it down when the installation is complete. RW RUNWAITEND Indicates that the installer should start the program and then wait until it has completed before resuming the installation.

• If RE or RW is not specified, then the installer runs the file and continues with the installation. It does not wait for the started program to complete.

This format is used to specify a list of files, of which only one will be installed, depending on the language selected by the user during installation:

{ "Source FileName"..."Source FileName"}-"Destination"[,Arguments]

This format will commonly be used to specify lists of resource files. Like applications, resource files must be installed to \system\apps\appname\appname.rsc. If the appname directory does not exist, it will be created.

For example;

{
"examples\ToolsAndUtilities\Install\HelloWorld.ruk"
"examples\ToolsAndUtilities\Install\HelloWorld.rfr"
"examples\ToolsAndUtilities\Install\HelloWorld.rit"
}-"!:\system\apps\HelloWorld\HelloWorld.rsc"

Here, three compiled resource files are specified, but only one will be installed on the target machine. Whichever language is chosen, the resource file will be installed as HelloWorld.rsc.

• The opening brace denotes the start of the block of language-dependent files.

• The order of the files should be the same as the order in which the languages were specified in the languages line

• The number of files specified must be the same as the number of languages supported.

• Options may appear after the destination name — as for the previous section, e.g. use FT to display a language specific dialog.

A requisite component is one that is required by the component which is being installed. It must be present on the target machine and its major and minor build numbers must be the same as, or greater than, those specified — otherwise installation will fail. Its name does not need to match the name specified, as it is identified by UID. However the name will be displayed to the user if there is a problem, e.g. the component is missing.

A requisite component is specified in the following way;

(UID),Major,Minor,Build-Number,{"Requisite Name1", " Requisite Name2"}

For example;

; Depends on STDLIB being installed
(0x100002c3), 1, 0, 14, {"Standard C Library"}

• When de-installation of a component involves the removal of another component's requisite files, the user is warned that continuing may prevent other programs from working.

• When the installer checks for the presence of requisites it uses the information specified in the package header of the target component's pkg file, see the Package header section.

• Installation files of type SISCONFIG, SISPATCH, and SISUPGRADE, must declare a dependency on the main component which they are affecting.

One or more embedded sis files may be specified, to be installed as part of the installation of the main component. Embedded sis files are removed when the component within which they were embedded is removed, provided no other component has a dependency upon them.

They are specified in the following way;

@ source-filename,(component-uid)

For example;

@"CsHelpExample.sis",(0x100002c3)

A capabilities line is used in conjunction with the Symbian Connect capabilities manager, or with the pkg appcap() function in a condition block. The capabilities manager may be used to determine the capabilities of a device or installed applications. The capabilities line is specified in the following way;

+(capid=value,…)

Device and application capabilities may be used to control specific behaviour when software is installed via a sis file or PC based software.

Device capabilities (hardware related) may also be set when the Symbian OS device's ROM is built. The pkg file devcap() function may be used to query device capability values within a condition block.

Application capabilities are defined when a sis file is created and stored on the device in the sis stub files. Application capabilities are key/value pairs whose meaning is application specific. The capid value is a unique application specific value and the associated value is an integer which may be queried via the capabilities manager PC based interface or using the appcap() pkg file syntax in an IF…ENDIF construct.

Lines of comment are preceded by a semicolon. They are ignored by the Installation File Generator