Package file format — `.pkg`

Overview
Languages
Installation header
Language independent files
Language dependent files
Requisites
.sis component files
Comments

Overview

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

the languages supported
the installation header, including the name of the component to be installed and its build and version information
non-language dependent files to install
language-dependent files, of which only one will be installed
requisite files
component .sis files
comments

The following topics define the structure of each of these components. For information about how to interpret the syntax, see BNF grammars.

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 languages section, see Language dependent files below. 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

Installation header

The installation 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,Variant,Arguments

Arguments

`ID`	The ID flag is present but not implemented. If specified, indicates that a copy of the component may be distributed to another machine. Otherwise the component cannot be distributed.
`IU`	Should be specified if the application's build variant is Unicode. EPOC Install will not install IU flagged SIS files at present.

For example;

    #{"Minimal application", "Application minimale", "Applicazione minima"},(0x01000508),1,0,0

All numbers can be hexadecimal.

Notes

The UID identifies the sub-subtype of the component which is to be installed, that is, its final UID. For more information about the role of UIDs in EPOC, view the appropriate section in your SDK.
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.
The variant number is currently not used by makesis, and may be omitted. For more information see Requisites, below.

Language independent files

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

"Source"-"Destination"[,Arguments]

For example:

    "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.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 EPOC machine. A destination must be specified unless the file is a text file. Text files, as indicated by an FT argument, are not installed. Consequently their destination is irrelevant, and may consist of empty quotes.

Note that EIKON applications must be built 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.

If the file must be installed on a specific drive, e.g. on c: for RAM, d: etc. for removable media, the drive letter should be specified. Otherwise !: may be used to indicate that the drive can be specified by the user at installation time.

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 installation header, and include the new .sis file in the .sis component files section, described below.

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`	Standard file. This is the default.
`FT`	Text file whose contents will be displayed in a dialog box during installation. The dialog will contain 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`	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. 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.
`FR`	A file which will be installed on the EPOC machine, 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.

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`	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`	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 specified in the `.pkg` file will not be installed.
`TA`	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.

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 Word document providing information about the new application.

RI

Run the file during installation only. This is the default.

RR

Run the file during removal only.

The file is deleted during removal, and hence should be able to run quickly — e.g., to clean up registry. A document should not be run during removal, as it will be deleted before it can be displayed.

RB

Run the file during both installation and removal.

The file is deleted during removal, and hence should be able to run quickly.

Language dependent files

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]

Notes

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.
The arguments are the same as for the previous section

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;

    {
    "\epoc32ex\adk\ikhello.ruk"
    "\ epoc32ex \adk\ikhello.rfr"
    "\ epoc32ex \adk\ikhello.rit"
    }-"!:\system\apps\ikhello\ikhello.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 ikhello.rsc.

Requisites

A requisite file 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.

A requisite file is specified in the following way;

(UID),Major,Minor,Variant,{"Requisite Name1", " Requisite Name2"}

For example;

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

Notes

Installation currently ignores the variant number, and this field may be omitted in the requisite definition.
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.
Requisite definitions use information specified in the installation header of the target component’s .pkg file, see Installation header.

`.sis` component files

One or more .sis component files may be specified, to be installed as part of the installation. They are specified in the following way;

@"ComponentFile.sis",(UID)

For example;

    @"STDLIB.SIS",(0x100002c3)

The component filename must have a .sis extension. If more than one .sis file is specified, they are installed in the order in which they are listed. The UID may be found in the installation header in the .sis file's .pkg file.

Comments

Lines of comment are preceded by a semi-colon. They are ignored by makesis.

Contents