|
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 reference |
|
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
|
12 <reference id="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324" xml:lang="en"><title>Language-Neutral |
|
13 Files</title><abstract><p>Language-Neutral files are files that are required to be installed |
|
14 irrespective of the languages supported on the Symbian device.</p><p>This |
|
15 Language-Neutral files section specifies the location and name of each file |
|
16 on the PC and its target location on the Symbian device. Files are installed |
|
17 in the order in which they are specified in the PKG file. </p></abstract><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
18 <refsyn id="GUID-744D2F39-8483-44C0-B335-03882385063E"><title>Syntax</title> <codeblock id="GUID-8B696DC5-3F23-5AD6-AECC-651887995037" xml:space="preserve">"source-filename" - "destination-filename"[, install-options]</codeblock> <p>where </p> <table id="GUID-B9A07521-29B4-5F5C-925F-B261E52FB1D6"> |
|
19 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
20 <tbody> |
|
21 <row> |
|
22 <entry><p> <b>Argument</b> </p> </entry> |
|
23 <entry><p> <b>Description</b> </p> </entry> |
|
24 </row> |
|
25 <row> |
|
26 <entry><p>source-filename </p> </entry> |
|
27 <entry><p>Specifies the name and location of the file on computer that must |
|
28 be included in the SIS file. </p> </entry> |
|
29 </row> |
|
30 <row> |
|
31 <entry><p>destination-filename </p> </entry> |
|
32 <entry><p>Specifies the location on the Symbian device, to which the file |
|
33 must be installed. See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-1584AED6-8583-51FC-AF7A-24C135DDC5AA">destination-filename</xref> for more information. </p> </entry> |
|
34 </row> |
|
35 <row> |
|
36 <entry><p>install-options </p> </entry> |
|
37 <entry><p>Specifies the type of file and how it affects the installation or |
|
38 removal. It is an optional comma-separated list. See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-E2911CFD-7B9D-55B7-86D1-4DA68870944D">install-options</xref>, for more information. </p> </entry> |
|
39 </row> |
|
40 </tbody> |
|
41 </tgroup> |
|
42 </table> <p id="GUID-1584AED6-8583-51FC-AF7A-24C135DDC5AA"><b>destination-filename</b> </p> <p>The <codeph>destination-filename</codeph> must |
|
43 specify the full path. A <codeph>!</codeph> character can be used instead |
|
44 of a drive letter to enable the Symbian device user to install the file to |
|
45 any required location. As an alternative to <codeph>!</codeph>, the <codeph>$</codeph> character |
|
46 can be used to denote the system drive. </p> <p>The <codeph>destination-filename</codeph> must |
|
47 not be specified if the file is not required to be installed. For example, |
|
48 a text file containing a licence agreement to be displayed during the installation |
|
49 must not include destination-filename and can be specified with empty quotes. </p> <p>If |
|
50 a file can be installed by other packages, for example, a shared DLL, it is |
|
51 recommended to install it using an embedded SIS file. </p> <p>The <codeph>destination-filename</codeph> can |
|
52 be specified in one of the following formats: </p> <codeblock id="GUID-D15405BA-B72F-5985-8713-966A33F4B257" xml:space="preserve">"drive:path"</codeblock> <codeblock id="GUID-96AF5EF7-B7BA-5B98-83E8-55D49A4C36AF" xml:space="preserve">"!:path"</codeblock> <codeblock id="GUID-50AA0C70-D535-5436-8732-875D24196EA0" xml:space="preserve">""</codeblock> <p id="GUID-E2911CFD-7B9D-55B7-86D1-4DA68870944D"><b> install-options</b> </p> <p>The |
|
53 following table provides a list of the <codeph>install-options</codeph>. </p> <table id="GUID-947C0669-A1F7-52F7-985F-3F75FFBB17C4"> |
|
54 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
55 <thead> |
|
56 <row> |
|
57 <entry>Name</entry> |
|
58 <entry>Abbreviation</entry> |
|
59 <entry>Description</entry> |
|
60 </row> |
|
61 </thead> |
|
62 <tbody> |
|
63 <row> |
|
64 <entry><p> <codeph>FILE</codeph> </p> </entry> |
|
65 <entry><p> <codeph>FF</codeph> </p> </entry> |
|
66 <entry><p>Specifies a standard installable file. For example: </p> <codeblock id="GUID-923A445F-87A5-5D0C-8B28-A6656D7D8830" xml:space="preserve">"text\file1.txt"-"!:\private\E800005A\file1.txt", FF</codeblock> </entry> |
|
67 </row> |
|
68 <row> |
|
69 <entry><p> <codeph>FILETEXT</codeph> </p> <p> <codeph>[,text-options]</codeph> </p> </entry> |
|
70 <entry><p> <codeph>FT</codeph> </p> <p> <codeph>[,text-options]</codeph> </p> </entry> |
|
71 <entry><p>A text file that is displayed in a dialog box during installation. |
|
72 The dialog type is determined by the <codeph>text-options</codeph> specified. |
|
73 See, <xref href="GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita#GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324/GUID-E6210579-BFAB-505B-A99F-99175FA0F572">text-options</xref> for |
|
74 more information. </p> <p>Text files are not installed on the target device, |
|
75 so the target location is empty. An example <codeph>FILETEXT</codeph> line |
|
76 is: </p> <codeblock id="GUID-D0728FED-F1A1-5574-BC3B-A24B8A881760" xml:space="preserve">"text\textfilec.txt"-"", FT, TC</codeblock> <p>Any <codeph>FILETEXT</codeph> statements |
|
77 present in a PKG file for a preinstalled application are ignored by the software |
|
78 installer. </p> </entry> |
|
79 </row> |
|
80 <row> |
|
81 <entry><p> <codeph>FILERUN</codeph> </p> <p> <codeph>[,run-options][,RUNWAITEND]</codeph> </p> </entry> |
|
82 <entry><p> <codeph>FR</codeph> </p> <p> <codeph>[,run-options][,RW]</codeph> </p> </entry> |
|
83 <entry><p>Specifies a file that is installed on the Symbian device and run |
|
84 during installation or uninstallation of packages based on the <codeph>RI</codeph>, <codeph>RR</codeph> and <codeph>RB</codeph> arguments. |
|
85 For details, 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>. </p> <p>For |
|
86 example: </p> <codeblock id="GUID-D985FEB8-4E60-5897-AFE0-89D723EA9350" xml:space="preserve">"\epoc32\release\armv5\urel\zoom.exe"-"!:\sys\bin\zoom.exe", FILERUN, RUNINSTALL</codeblock> <p> <b>Notes</b>: </p> <ul> |
|
87 <li id="GUID-62883591-AE70-5ABA-B86B-232084BCACF1"><p>The file can be an executable |
|
88 or a document containing text. </p> </li> |
|
89 <li id="GUID-84B90271-D1A2-578B-AC19-52B04DC9284C"><p>The untrusted applications |
|
90 are run through the <codeph>FILERUN</codeph> (<codeph/><codeph>FR</codeph>) |
|
91 or <codeph>FILEMIME</codeph> (<codeph>FM</codeph>) statements based on configuration |
|
92 of the installation policy. </p> </li> |
|
93 </ul> </entry> |
|
94 </row> |
|
95 <row> |
|
96 <entry><p> <codeph>FILEMIME,</codeph> </p> <p> <codeph>mime-type</codeph> </p> <p> <codeph>,run-options</codeph> </p> <p> <codeph>[,RUNWAITEND]</codeph> </p> </entry> |
|
97 <entry><p> <codeph>FM,</codeph> </p> <p> <codeph>mime-type</codeph> </p> <p> <codeph>,run-options |
|
98 [,RW]</codeph> </p> </entry> |
|
99 <entry><p>Instructs the installer to associate the file with the default application |
|
100 associated with the given MIME type, for example, <codeph>text or |
|
101 x-vCard</codeph> is required to be open for contact details. </p> <p>The |
|
102 MIME type in quotes must be specified after the <codeph>FM</codeph> argument. <codeph>FILEMIME</codeph> is |
|
103 intended for use with files that are launched during the installation or uninstallation |
|
104 and not for standard installation files. For example: </p> <codeblock id="GUID-94D600A6-C80A-5EBB-8240-D481CD24E27B" xml:space="preserve">"my_picture.gif"-"", FM, "image/gif", RI</codeblock> <p>The Software Installer ignores any <codeph>FILEMIME</codeph> statements |
|
105 present in a PKG file for a preinstalled application. </p> </entry> |
|
106 </row> |
|
107 </tbody> |
|
108 </tgroup> |
|
109 </table> <p id="GUID-E6210579-BFAB-505B-A99F-99175FA0F572"><b>text-options</b> </p> <p> <codeph>text-options</codeph> can |
|
110 be used after <codeph>FT</codeph> is specified. It is used by the UI to determine |
|
111 the type of dialog that is used to display the text. It can have one of the |
|
112 following values. </p> <table id="GUID-2DDEC392-244A-505C-B102-EBE19D8A3CC3"> |
|
113 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
114 <thead> |
|
115 <row> |
|
116 <entry>Name</entry> |
|
117 <entry>Abbreviation</entry> |
|
118 <entry>Description</entry> |
|
119 </row> |
|
120 </thead> |
|
121 <tbody> |
|
122 <row> |
|
123 <entry><p> <codeph>TEXTCONTINUE</codeph> </p> </entry> |
|
124 <entry><p> <codeph>TC</codeph> </p> </entry> |
|
125 <entry><p>It is recommended that the UI displays a dialog containing a <codeph>Continue</codeph> button. </p> <p>The |
|
126 installation continues regardless of the return value of the dialog. </p> </entry> |
|
127 </row> |
|
128 <row> |
|
129 <entry><p> <codeph>TEXTABORT</codeph> </p> </entry> |
|
130 <entry><p> <codeph>TA</codeph> </p> </entry> |
|
131 <entry><p>It is recommended that the UI displays a dialog containing <codeph>Yes</codeph> /<codeph>No</codeph> buttons. </p> <p>The |
|
132 software installer continues with the installation if the dialog returns true |
|
133 (if the Symbian device user selects <codeph>Yes</codeph>). It aborts the installation |
|
134 if the dialog returns false (if the Symbian device user selects <codeph>No</codeph>). </p> </entry> |
|
135 </row> |
|
136 <row> |
|
137 <entry><p> <codeph>TEXTEXIT</codeph> </p> </entry> |
|
138 <entry><p> <codeph>TE</codeph> </p> </entry> |
|
139 <entry><p>Same as <codeph>TEXTABORT</codeph>. </p> </entry> |
|
140 </row> |
|
141 <row> |
|
142 <entry><p> <codeph>FORCEABORT</codeph> </p> </entry> |
|
143 <entry><p> <codeph> FA </codeph> </p> </entry> |
|
144 <entry><p>It is recommended that the UI displays a dialog containing a <codeph>ForceAbort</codeph> button. </p> <p>On |
|
145 selecting this dialog, it aborts the installation. </p> </entry> |
|
146 </row> |
|
147 <row> |
|
148 <entry><p><codeph>TEXTSKIP</codeph></p></entry> |
|
149 <entry><p><codeph>TS</codeph></p></entry> |
|
150 <entry><p>It is recommended that the UI displays a dialog containing <codeph>Yes</codeph> /<codeph>No</codeph> buttons. </p><p>The |
|
151 software installer continues the installation without skipping |
|
152 the file mentioned in the next statement if the dialog returns true (if the |
|
153 Symbian device user selects <codeph>Yes</codeph>). It skips the installation |
|
154 of the file mentioned in the next statement if the dialog returns false (if |
|
155 the Symbian device user selects <codeph>No</codeph>).</p></entry> |
|
156 </row> |
|
157 </tbody> |
|
158 </tgroup> |
|
159 </table> <p> <b>Note</b>: UIs can implement installation dialogs differently, |
|
160 so you must refer to the UI SDK for details about the actual behaviour. </p> <p id="GUID-B913501B-A5AB-5ADB-96FF-8060DD45A87E"><b>run-options</b> </p> <p> <codeph> run-options</codeph> can |
|
161 be used after <codeph>FR</codeph> or <codeph>FM</codeph> has been specified. |
|
162 It can be any of the following: </p> <table id="GUID-7B193CA1-4057-5680-93E3-9DC931924D3B"> |
|
163 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
164 <thead> |
|
165 <row> |
|
166 <entry>Name</entry> |
|
167 <entry>Abbreviation</entry> |
|
168 <entry>Description</entry> |
|
169 </row> |
|
170 </thead> |
|
171 <tbody> |
|
172 <row> |
|
173 <entry><p> <codeph>RUNINSTALL</codeph> </p> </entry> |
|
174 <entry><p> <codeph>RI</codeph> </p> </entry> |
|
175 <entry><p>Run on install </p> </entry> |
|
176 </row> |
|
177 <row> |
|
178 <entry><p> <codeph>RUNREMOVE</codeph> </p> </entry> |
|
179 <entry><p> <codeph>RR</codeph> </p> </entry> |
|
180 <entry><p>Run on uninstall and upgrade </p> </entry> |
|
181 </row> |
|
182 <row> |
|
183 <entry><p> <codeph>RUNBOTH</codeph> </p> </entry> |
|
184 <entry><p> <codeph>RB</codeph> </p> </entry> |
|
185 <entry><p>Run on install, uninstall and upgrade </p> </entry> |
|
186 </row> |
|
187 <row> |
|
188 <entry><p> <codeph>RUNBEFORESHUTDOWN</codeph> </p> </entry> |
|
189 <entry><p> <codeph>RBS</codeph> </p> </entry> |
|
190 <entry><p>Run on uninstall before the applications in the package are shut |
|
191 down </p> </entry> |
|
192 </row> |
|
193 </tbody> |
|
194 </tgroup> |
|
195 </table> <p>Optionally, <codeph>RW</codeph> (or <codeph>RUNWAITEND</codeph>) |
|
196 can be specified in addition to the <codeph>run-options</codeph>. If this |
|
197 option is specified, the installation server waits for the program to terminate |
|
198 before continuing with the install. If this option is not specified, the installation |
|
199 server runs the program and continues with the installation. The program is |
|
200 shut down after the installation is complete. </p><p>When uninstalling a package |
|
201 with a <codeph>RUNREMOVE</codeph> or <codeph>RUNBOTH</codeph> executable specified, |
|
202 the installation server always waits for the executable to terminate or timeout |
|
203 before continuing with the uninstall.</p> <p><b>Verification options</b> </p> <p>The |
|
204 following option is available for checking the integrity of a file at restore |
|
205 time: </p> <table id="GUID-78249B09-3D1C-5A89-AC4B-BA53DA2ACA4F"> |
|
206 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
207 <thead> |
|
208 <row> |
|
209 <entry>Name</entry> |
|
210 <entry>Abbreviation</entry> |
|
211 <entry>Description</entry> |
|
212 </row> |
|
213 </thead> |
|
214 <tbody> |
|
215 <row> |
|
216 <entry><p> <codeph>VERIFY</codeph> </p> </entry> |
|
217 <entry><p> <codeph>VR</codeph> </p> </entry> |
|
218 <entry><p>This flag is necessary if the integrity of a file installed in a |
|
219 directory outside <filepath>\sys</filepath> or <filepath>\restore</filepath> needs |
|
220 to be verified at restore time. For example, an application can check this |
|
221 flag to verify that a security policy file restored to its private directory |
|
222 is identical to the file delivered by the SIS file. </p> <p>The following |
|
223 example illustrates the usage of this option: </p> <codeblock id="GUID-1E310E2B-94BB-5877-91E6-14C5895BCF91" xml:space="preserve">"data\ups_01041000_01041001.rsc"- |
|
224 "$:\private\10283558\policies\ups_01041000_01041001.rsc", VERIFY</codeblock> </entry> |
|
225 </row> |
|
226 </tbody> |
|
227 </tgroup> |
|
228 </table> <p id="GUID-90E6B97B-3A6A-5D88-80D1-B66248C82543"><b>Import and Private |
|
229 Directories</b> </p> <p>The software installer ensures that files are placed |
|
230 in appropriate areas of the file system. The following rules are applied: </p> <ul> |
|
231 <li id="GUID-F92635A7-7B97-5CA8-8C2C-E2E52CBB279C"><p>A package can only deliver |
|
232 a data file into the private directory belonging to any executable in the |
|
233 package. If a package delivers three executables: <codeph>SID1</codeph>, <codeph>SID2</codeph>, <codeph>SID3</codeph> (where |
|
234 SID stands for Secure ID), then data files can be delivered to <filepath>/private/SID1/</filepath>, <filepath>/private/SID2/</filepath>, |
|
235 or <filepath>/private/SID3/</filepath>. In an upgrade, this is possible by |
|
236 associating the upgrade package with the SIDs present in the original package |
|
237 unless one of the original executables is to be removed during the upgrade. </p> </li> |
|
238 <li id="GUID-AB6861A6-C1DB-5F82-B621-798D8C131417"><p>Any package can deliver |
|
239 a file into the <filepath>//private/SID/import</filepath> of an entirely unrelated |
|
240 package. However, replacement and eclipsing rules apply. </p> </li> |
|
241 </ul> </refsyn> |
|
242 </refbody></reference> |