The PKG file supporting upgrades must contain package-header section with definitions for different types of upgrades. For details see, Package-Header.
The following table lists the different types of upgrades possible:
Type |
Package UID |
Package name |
Version |
Global vendor name |
Notes |
SA |
Same |
Same |
Higher (not mandatory) |
Same |
Can overwrite (replace) files |
SP |
Same |
Different |
Not required |
Not required |
Cannot overwrite (replace) files |
PU |
Same |
Need not match |
Higher (not mandatory) |
Not required |
Can overwrite (replace) files |
The full upgrade is specified using the SA tag in the package-header. In full upgrade, the original package is entirely replaced by the new one. The original files that are not available in the new package are removed from the Symbian device. After upgrade, the new package cannot be removed separately from the original. To remove the upgrade, the entire package must be removed.
If the upgrade causes an executable to be removed, the corresponding private directory is deleted. Any folders and files that are created by the application outside its private directory are not removed. The application must remove these files.
Important: It is recommended that files created by an application be located in the private directory of the application.
If the upgrade causes an executable to be replaced, the private directory is not removed.
Notes:
An upgrading package of type SA cannot overwrite files installed by a patch. For upgrading such packages, the patch must be uninstalled first.
To be identified as an upgrade, the upgrading package file must have the same package UID as the original. If the package UID differs, it is considered to be an unrelated package and not an upgrade.
If a patch upgrades an SA package, the patch is not uninstalled by new SA upgrade.
The RR and RB executables in the base package are run during the upgrade. See, run-options for details.
The patch upgrade is specified using the SP tag in the package-header. This is an augmentation to an existing package (base package). A typical example for this requirement is to provide additional levels of a game. A patch upgrade cannot overwrite files in RAM, however, it can eclipse files in ROM. A patch can be uninstalled separately from the base package. The installation fails if a patch modifies or replaces an existing file in the base package.
A patch can only add files to a base package and cannot overwrite files. This is the only difference between patch upgrade and partial upgrade.
Notes:
If two patches with same package name and UID are installed, the second patch is treated as an upgrade of the first patch. The second patch replaces the first patch entirely.
An OS component does not need a Stub SIS file to be patched. However, if the requirement is to patch files in the private directory of the component, a stub SIS file is required which specifies the relevant executables (.exe).
Important: If the patch installs files to more than one private directory, all relevant EXEs must be specified in the Stub file.
If a Stub SIS file is required, the patch must have the same package UID and non-localized vendor name as the package it is upgrading. The package name must be different to distinguish the patch from the existing component.
A patch can install files to the import directory of the component (\private\ <SID> \import\) without the requirement of a Stub SIS file. However, the import directory must already exist. The software installer does not create it.
The purpose of the import directory is to enable other packages to install files to it.
The partial upgrade is specified using the PU tag in the package-header. This upgrade is a variation of SA in that any files present in the base package that are missing in the new package are not removed. A partial upgrade can only add or overwrite files. This allows an upgrading SIS file to replace just the parts of a base package which requires replacement.
Notes:
When creating a PU package, the drive selection dialog must be suppressed, so that the upgrade is installed on the same drive as the existing package and not to the drive selected by the Symbian device user.
Unlike packages installed using the SA or SP options, a partial upgrade package is not listed as a removable component after installation, so the base package must be removed and reinstalled to remove the changes.
A partial upgrade cannot overwrite files installed by a patch.
The RR and RB executables in the base package are run during the upgrade. See, run-options for details.
It is not mandatory to specify the RU option for upgrading applications on the ROM.