Installing language independent files

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.

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

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

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

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

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

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
  RUNBEFORESHUTDOWN	RBS	Run on uninstall before the applications in the package are shut down

• 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.

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 following option is available for checking the integrity of a file at restore time:

"data\ups_01041000_01041001.rsc"-
"$:\private\10283558\policies\ups_01041000_01041001.rsc", VERIFY

Note: the VERIFY flag is supported in version 5.1.0.1 or higher of makesis.

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.