|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-7FD72D9F-D65E-5248-A296-F2196F1DF5CF" xml:lang="en"><title> Upgrade |
|
13 Types</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The PKG file supporting upgrades must contain package-header section with |
|
15 definitions for different types of upgrades. For details see, <xref href="GUID-D9D20EE0-AC86-512A-91C0-EA0ACF3912A7.dita">Package-Header</xref>. </p> |
|
16 <p>The following table lists the different types of upgrades possible: </p> |
|
17 <table id="GUID-F082562E-66EA-58F7-A77A-ED512E9E7FA7"> |
|
18 <tgroup cols="6"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/><colspec colname="col5"/> |
|
19 <tbody> |
|
20 <row> |
|
21 <entry><p> <b>Type</b> </p> </entry> |
|
22 <entry><p> <b>Package UID</b> </p> </entry> |
|
23 <entry><p> <b>Package name</b> </p> </entry> |
|
24 <entry><p> <b>Version</b> </p> </entry> |
|
25 <entry><p> <b>Global vendor name</b> </p> </entry> |
|
26 <entry><p> <b>Notes</b> </p> </entry> |
|
27 </row> |
|
28 <row> |
|
29 <entry><p> <codeph>SA</codeph> </p> </entry> |
|
30 <entry><p>Same </p> </entry> |
|
31 <entry><p>Same </p> </entry> |
|
32 <entry><p>Higher (not mandatory) </p> </entry> |
|
33 <entry><p>Same </p> </entry> |
|
34 <entry><p>Can overwrite (replace) files </p> </entry> |
|
35 </row> |
|
36 <row> |
|
37 <entry><p> <codeph>SP</codeph> </p> </entry> |
|
38 <entry><p>Same </p> </entry> |
|
39 <entry><p>Different </p> </entry> |
|
40 <entry><p>Not required </p> </entry> |
|
41 <entry><p>Not required </p> </entry> |
|
42 <entry><p>Cannot overwrite (replace) files </p> </entry> |
|
43 </row> |
|
44 <row> |
|
45 <entry><p> <codeph>PU</codeph> </p> </entry> |
|
46 <entry><p>Same </p> </entry> |
|
47 <entry><p>Need not match </p> </entry> |
|
48 <entry><p>Higher (not mandatory) </p> </entry> |
|
49 <entry><p>Not required </p> </entry> |
|
50 <entry><p>Can overwrite (replace) files </p> </entry> |
|
51 </row> |
|
52 </tbody> |
|
53 </tgroup> |
|
54 </table> |
|
55 <section><title>SA - Full Upgrade</title> <p>The full upgrade is specified |
|
56 using the <codeph>SA</codeph> tag in the package-header. In full upgrade, |
|
57 the original package is entirely replaced by the new one. The original files |
|
58 that are not available in the new package are removed from the Symbian device. |
|
59 After upgrade, the new package cannot be removed separately from the original. |
|
60 To remove the upgrade, the entire package must be removed. </p> <p>If the |
|
61 upgrade causes an executable to be <i>removed</i>, the corresponding private |
|
62 directory is deleted. Any folders and files that are created by the application |
|
63 outside its private directory are not removed. The application must remove |
|
64 these files. </p> <p> <b>Important:</b> It is recommended that files created |
|
65 by an application be located in the private directory of the application. </p> <p>If |
|
66 the upgrade causes an executable to be <i>replaced</i>, the private directory |
|
67 is not removed. </p> <p> <b>Notes</b>: </p> <ul> |
|
68 <li id="GUID-E726EE1F-F977-5DDA-9AFD-E0AEEC789D6D"><p>An upgrading package |
|
69 of type <codeph>SA</codeph> cannot overwrite files installed by a patch. For |
|
70 upgrading such packages, the patch must be uninstalled first. </p> </li> |
|
71 <li id="GUID-18DB72B9-55EC-581C-B705-343720F62B34"><p>To be identified as |
|
72 an upgrade, the upgrading package file must have the same package UID as the |
|
73 original. If the package UID differs, it is considered to be an unrelated |
|
74 package and not an upgrade. </p> </li> |
|
75 <li id="GUID-76D8A7B8-3DD2-5D14-835A-031C2B1EE0C8"><p>If a patch upgrades |
|
76 an <codeph>SA</codeph> package, the patch is not uninstalled by new <codeph>SA</codeph> upgrade. </p> </li> |
|
77 <li id="GUID-EEEE413A-522E-52D2-9B8B-BA5933DD0000"><p>The <codeph>RR</codeph> and <codeph>RB</codeph> executables |
|
78 in the base package are run during the upgrade. See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-B913501B-A5AB-5ADB-96FF-8060DD45A87E">run-options</xref> for details. </p> </li> |
|
79 </ul> </section> |
|
80 <section><title>SP - Patch Upgrade</title> <p>The patch upgrade is specified |
|
81 using the <codeph>SP</codeph> tag in the package-header. This is an augmentation |
|
82 to an existing package (<i>base package</i>). A typical example for this requirement |
|
83 is to provide additional levels of a game. A patch upgrade cannot overwrite |
|
84 files in RAM, however, it can eclipse files in ROM. A patch can be uninstalled |
|
85 separately from the base package. The installation fails if a patch modifies |
|
86 or replaces an existing file in the base package. </p> <p>A patch can only |
|
87 add files to a base package and cannot overwrite files. This is the only difference |
|
88 between patch upgrade and partial upgrade. </p> <p> <b>Notes</b>: </p> <ul> |
|
89 <li id="GUID-BDE060BA-2846-5E05-93BD-CEE9136651A7"><p>If two patches with |
|
90 same package name and UID are installed, the second patch is treated as an |
|
91 upgrade of the first patch. The second patch replaces the first patch entirely. </p> </li> |
|
92 <li id="GUID-92611923-8DEB-5E45-89D5-9712C1C26CD4"><p>An OS component does |
|
93 not need a Stub SIS file to be patched. However, if the requirement is to |
|
94 patch files in the private directory of the component, a stub SIS file is |
|
95 required which specifies the relevant executables (<filepath>.exe</filepath>). </p> <p> <b>Important</b>: |
|
96 If the patch installs files to more than one private directory, all relevant |
|
97 EXEs must be specified in the Stub file. </p> <p>If a Stub SIS file is required, |
|
98 the patch must have the same package UID and non-localized vendor name as |
|
99 the package it is upgrading. The package name must be different to distinguish |
|
100 the patch from the existing component. </p> </li> |
|
101 <li id="GUID-ED91317F-65E8-5E52-AFE4-5D5A94126AA1"><p>A patch can install |
|
102 files to the import directory of the component (<filepath>\private\</filepath> <i><SID></i> <filepath>\import\</filepath>) |
|
103 without the requirement of a Stub SIS file. However, the import directory |
|
104 must already exist. The software installer does not create it. </p> <p>The |
|
105 purpose of the import directory is to enable other packages to install files |
|
106 to it. </p> </li> |
|
107 </ul> </section> |
|
108 <section><title>PU - Partial Upgrade</title> <p>The partial upgrade is specified |
|
109 using the <codeph>PU</codeph> tag in the package-header. This upgrade is a |
|
110 variation of <codeph>SA</codeph> in that any files present in the base package |
|
111 that are missing in the new package are not removed. A partial upgrade can |
|
112 only add or overwrite files. This allows an upgrading SIS file to replace |
|
113 just the parts of a base package which requires replacement. </p> <p> <b>Notes</b>: </p> <ul> |
|
114 <li id="GUID-3EAFFA91-9929-5E94-825C-6CF648886A77"><p>When creating a <codeph>PU</codeph> package, |
|
115 the drive selection dialog must be suppressed, so that the upgrade is installed |
|
116 on the same drive as the existing package and not to the drive selected by |
|
117 the Symbian device user. </p> </li> |
|
118 <li id="GUID-349A16C1-3876-5B90-AD15-56027407EA08"><p>Unlike packages installed |
|
119 using the <codeph>SA</codeph> or <codeph>SP</codeph> options, a partial upgrade |
|
120 package is not listed as a removable component after installation, so the |
|
121 base package must be removed and reinstalled to remove the changes. </p> </li> |
|
122 <li id="GUID-3E6FDB35-55D5-5BD7-9E0E-C60F5D6B7476"><p>A partial upgrade cannot |
|
123 overwrite files installed by a patch. </p> </li> |
|
124 <li id="GUID-B335BF5B-B45C-558F-BDEE-09C2676AC133"><p>The <codeph>RR</codeph> and <codeph>RB</codeph> executables |
|
125 in the base package are run during the upgrade. See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-B913501B-A5AB-5ADB-96FF-8060DD45A87E">run-options</xref> for details. </p> </li> |
|
126 <li id="GUID-CCCCE6F7-EA61-5617-A692-D57EB856C133"><p>It is not mandatory |
|
127 to specify the RU option for upgrading applications on the ROM. </p> </li> |
|
128 </ul> </section> |
|
129 </conbody><related-links> |
|
130 <link href="GUID-D9D20EE0-AC86-512A-91C0-EA0ACF3912A7.dita"><linktext>Package-Header</linktext> |
|
131 </link> |
|
132 <link href="GUID-7F65B69A-6AC1-509C-91E8-9E49ED0BFEC0.dita"><linktext>Upgrading |
|
133 OS Components</linktext></link> |
|
134 </related-links></concept> |