Installing language independent files in install-file

The install-file section gives the location and name of each file on the PC to install onto the phone and its target location on the phone.

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

The syntax used is:

"source-filename" - "destination-filename"[, install-options]

These elements are explained in the following sections.

The source-filename gives the location and name of the file on the PC to be included in the SIS file.

The destination-filename gives the location on the phone to which the file should be installed. It should specify the full path. A ! character may be used instead of a drive letter to indicate that the user should be given the choice of drive to install the file to (if the phone has multiple drives). From v9.3 onwards, an alternative is to use the $ character, to denote the system drive.

A destination should not be specified if the file will not be installed, for example a text file containing a licence agreement to be displayed during the installation. Its destination is irrelevant, and may consist of empty quotes.

Prior to Symbian OS v9.x, files could be installed anywhere in the file system. From v9.1 onwards, data-caging imposes strict rules on file locations on the phone. See this table for a summary. Also, see Import and Private Directories section below.

If the file being installed may also be installed by other packages (for instance a shared DLL), it is recommended to install it using a separate, or an embedded SIS file, as explained here.

The destination-filename can have any of the following forms:

"drive:path"

"!:path"

""

An optional comma-separated list of install-options following the destination-filename may be specified, to describe the type of file and how it will affect the installation or removal process. The table below provides a list of the optional install-options.

Name Abbreviation Description

FILE

FF

Default -- Standard installable file. For instance:

"text\file1.txt"-"!:\private\E800005A\file1.txt", FF

FILENULL

FN

From v9.x, FILENULL is deprecated. However, it has been retained to ease migration of older PKG files to v9.x. See the Notes on FILENULL below these tables for more information.

FILENULL identifies a file or directory that does not exist at install time, but which will be 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 consist of empty quotes. Note that such files will not be deleted when upgrading to a later version. This ensures that files such as .ini files, which store application preferences, are not lost in an upgrade. Here are some example FILENULL lines:

""-"$:\private\E800005A\deleteme.txt", FN ""-"$:\private\E800005A\deleteme1\", FN ""-"$:\private\E800005A\deleteme2\*.*", FN

FILETEXT

[,text-options]

FT

[,text-options]

A text file that is displayed in a dialog box during installation. The dialog's type is determined by the text-options specified (documented below). Text files are not installed on the target device, so the target location is empty. An example FILETEXT line is:

"text\textfilec.txt"-"", FT, TC

Any FILETEXT statements present in a PKG file for a pre-installed application are ignored by the software installer.

FILERUN

[,run-options][,RUNWAITEND]

FR

[,run-options][,RW]

A file that will be installed on the device, and run during installation and/or removal — depending on arguments RI, RR, RB described later. The file could be an executable or a document. For instance:

"\epoc32\release\armv5\urel\zoom.exe"-"!:\sys\bin\zoom.exe", FILERUN, RUNINSTALL

Note that whether untrusted applications are allowed to execute via the FILERUN (FR) or FILEMIME (FM) directives depends on how the device manufacturer has configured the phone's installation policy.

Any FILERUN statements present in a PKG file for a pre-installed application are ignored by the software installer.

FILEMIME,

mime-type

,run-options

[,RUNWAITEND]

FM,

mime-type

,run-options [,RW]

Instructs the installer that it should pass the file to the default application associated with the given MIME type, for example text/x-vCard for contact details. The MIME type in quotes should be specified after the FM argument. FILEMIME is intended for use with files that are launched during the installation/uninstallation, not for standard install files. For example:

"my_picture.gif"-"", FM, "image/gif", RI

Note that whether untrusted applications are allowed to execute via the FILERUN (FR) or FILEMIME (FM) directives depends on how the device manufacturer has configured the phone's installation policy.

Any FILEMIME statements present in a PKG file for a pre-installed application are ignored by the software installer.

where:

text-options can be used after FT has been specified. It is used by the UI to determine the type of dialog that is used to display the text. It can have one of the following values. Note that UIs may implement installation dialogs differently, so you should refer to the UI's SDK for details of actual behaviour.

Name	Abbreviation	Description
`TEXTCONTINUE`	`TC`	It is recommended that the UI displays a dialog containing a `Continue` button. On exiting the dialog, installation continues regardless of the dialog's return value.
`TEXTABORT`	`TA`	It is recommended that the UI displays a dialog containing `Yes`/`No` buttons. The software installer continues with the installation if the dialog returns true (user pressed `Yes`). It will abort the installation if the dialog returns false (user pressed `No`).
`TEXTEXIT`	`TE`	Same as `TEXTABORT`.

run-options (which can be used after FR or FM has been specified) can be any of the following:

Name Abbreviation Description

RUNINSTALL

RI

Run on install

RUNREMOVE

RR

Run on uninstall and upgrade

RUNBOTH

RB

Run on install, uninstall and upgrade
Optionally, RW (or RUNWAITEND) can be specified in addition to the run-options. If it is not specified, the default behaviour is to run the program and continue with the install; the program will shut down when the install is complete. Specifying RW causes the install server to wait a reasonable amount of time for the program to terminate before continuing with the install.

When uninstalling a package with a RUNREMOVE or RUNINSTALL executable specified, the install server always waits for the executable to terminate or timeout before continuing with the uninstall.

Notes on FILENULL

The purpose of the FILENULL statement is to list files that should be deleted when the package is uninstalled, but which do not yet exist at install time. From v9.1 onwards, it should not be necessary to use FILENULL, and it has been deprecated.

To avoid using FILENULL, files should be created in the application's private directory (\private\<SID>\). When the application is uninstalled, the private directory and all its contents are removed. Because private directories are inaccessible to other processes (apart from the very few with AllFiles capability), files located there are secure.

Using unprotected directories is inherently insecure, and designing an application to make use of private directories instead will not only be more secure, but will provide straightforward cleanup on uninstall, with no need to use FILENULL.

Notes:

If the attempted removal of an FN file fails due to the file being locked or if the file server indicates that access is denied, this will not cause the whole uninstallation to fail, although that file will not be deleted.
Wildcards and directory names can be specified in FILENULL statements. The following three statements have the same effect:

""-"$:\documents\temp*", FN ""-"$:\documents\", FN ""-"$:\documents\*", FN

For security reasons, by default, deletion is not recursive, so that the three statements above will delete all files located in \documents\ but will not delete any subdirectories. This behaviour can be configured by the phone manufacturer.
If a root directory is specified in a FILENULL statement, the statement will be ignored. This will not cause the uninstallation to fail. Note that the following three lines have the same effect:

""-"$:\", FN ""-"$:\*", FN ""-"$:\temp*", FN
Installation will fail if a FILENULL statement refers to files in ROM.
If a package attempts to install a file which already exists and is referenced by another package only for FILENULL, it will be treated as an orphaned file. Overwriting of orphaned files may or may not be allowed, depending on the phone manufacturer's security policy. If allowed, the user will be given the option of overwriting it, and the installation will continue. If not allowed, installation will fail. To avoid such problems it is recommended to install files in private directories.

The software installer polices software installation to ensure that files are not placed in inappropriate areas of the file system. The following rules are applied:

A package can only deliver a data file into the private directory belonging to any executable in the package. If therefore, a package delivers 3 executables: SID1, SID2, SID3 (where SID stands for Secure ID), then data files can be delivered to /private/SID1/, /private/SID2/, or /private/SID3/. In an upgrade, this is also possible by associating the upgrade package with the SIDs present in the original package unless one of the original executables is to be removed during the upgrade.
Any package can deliver a file into the /private/SID/import directory of an entirely unrelated package. However, replacement and eclipsing rules apply.

Installing language independent files

`source-filename`

`destination-filename`

`install-options`

Notes on FILENULL

Import and Private Directories