|
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-51C5DC6C-0CEE-5F44-8578-AEFBEF90FA4D" xml:lang="en"><title>READIMAGE</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
13 <p>READIMAGE is a command-line tool that provides readable data from |
|
14 a ROM, ROFS, or E32 image. It can also generate an IBY file from a |
|
15 SIS file which can be used to generate a data drive image. </p> |
|
16 <section id="GUID-EB948089-0609-58A1-A87E-5B13B0DF1FE7"><title>Command |
|
17 syntax</title> <p>Run the following command to use the READIMAGE tool: </p> <p><userinput>readimage [options] <image filename> or <SIS |
|
18 filename></userinput> </p> <p>where: </p> <ul> |
|
19 <li id="GUID-396A2825-6CD1-5E0D-8E2E-40424D57CBBE"><p> <codeph><image |
|
20 filename></codeph> is an input <filepath>image</filepath> file </p> </li> |
|
21 <li id="GUID-6AB4C51E-F213-5755-BFF7-1416AC024D06"><p> <codeph> <sis |
|
22 filename></codeph> is an input <filepath>.sis</filepath> file. </p> </li> |
|
23 </ul> <p><b>Reading ROM, ROFS and E32 images</b> </p> <p>Run the following |
|
24 command to read a ROM, ROFS, or E32 image: </p> <p><userinput>readimage |
|
25 options <ROM/ROFS/E32 imagefile></userinput> </p> <p>The command |
|
26 line options are as follows: </p> <table id="GUID-A89CDF05-C34B-5091-96B8-F34F503B102B"> |
|
27 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
28 <thead> |
|
29 <row> |
|
30 <entry>Options</entry> |
|
31 <entry>Description</entry> |
|
32 </row> |
|
33 </thead> |
|
34 <tbody> |
|
35 <row> |
|
36 <entry><p> <codeph>-o</codeph> </p> </entry> |
|
37 <entry><p>Indicates output file name. </p> </entry> |
|
38 </row> |
|
39 <row> |
|
40 <entry><p> <codeph>-d</codeph> </p> </entry> |
|
41 <entry><p>Displays header information about the input image. </p> </entry> |
|
42 </row> |
|
43 <row> |
|
44 <entry><p> <codeph>-s</codeph> </p> </entry> |
|
45 <entry><p>Displays the directory structure of the input image. </p> </entry> |
|
46 </row> |
|
47 <row> |
|
48 <entry><p> <codeph>-v</codeph> </p> </entry> |
|
49 <entry><p>Displays image headers and the directory structure of the |
|
50 input image. </p> </entry> |
|
51 </row> |
|
52 <row> |
|
53 <entry><p> <codeph>-e</codeph> </p> </entry> |
|
54 <entry><p>Displays the E32 image from the input ROM or ROFS image. </p> </entry> |
|
55 </row> |
|
56 <row> |
|
57 <entry><p> <codeph>-h</codeph> </p> </entry> |
|
58 <entry><p>Displays help information. </p> </entry> |
|
59 </row> |
|
60 <row> |
|
61 <entry><p> <codeph>-z <path></codeph> </p> </entry> |
|
62 <entry><p>Extracts all files from the given image to the specified |
|
63 location. </p> </entry> |
|
64 </row> |
|
65 <row> |
|
66 <entry><p> <codeph>-l <logfile name></codeph> </p> </entry> |
|
67 <entry><p>Logs the image contents in a file. </p> </entry> |
|
68 </row> |
|
69 <row> |
|
70 <entry><p> <codeph>-x <pattern></codeph> </p> </entry> |
|
71 <entry><p>Extracts a single or a set of files from a ROM or ROFS image |
|
72 into the current directory. The pattern contains set of file names. |
|
73 For more information about <codeph><pattern></codeph>, see <xref href="GUID-C0D7E049-635B-5089-9C2F-55BE2481A77E.dita#GUID-C0D7E049-635B-5089-9C2F-55BE2481A77E/GUID-5ABC32C0-2D45-5A38-81A8-409B1E191007">Extracting a set of files</xref>. </p> </entry> |
|
74 </row> |
|
75 <row> |
|
76 <entry><p> <codeph>-r</codeph> </p> </entry> |
|
77 <entry><p>Recursively extracts the files from ROM or ROFS image. This |
|
78 option is always used with the <codeph>-x</codeph> option. </p> </entry> |
|
79 </row> |
|
80 </tbody> |
|
81 </tgroup> |
|
82 </table> <p> <b>Note</b>: Options are not case-sensitive. READIMAGE |
|
83 reports an error if an argument is not passed for the -x or -z option. </p> <p> <b><i>Extracting one file</i></b> </p> <p>The command below |
|
84 extracts all the files from <filepath>sample.img</filepath> to the <filepath>C:\test</filepath> location. </p> <p><userinput>readimage -z C:\test\ |
|
85 sample.img</userinput> </p> <p> <b><i>Extracting a set of files with |
|
86 wildcard ?</i></b> </p> <p>The READIMAGE tool provides the -x option |
|
87 to extract one or more files from a ROM or ROFS image, based on a |
|
88 pattern that matches the name of the file. A question mark(?) indicates |
|
89 to match one instance of any character in a file name, within the |
|
90 directory. </p> <p>The command below extracts all the <filepath>.exe </filepath> files from the <filepath>\sys\bin</filepath> directory present in |
|
91 the <filepath>sample.img</filepath> file, whose file name consists |
|
92 of two characters. </p> <p><userinput>readimage -x \sys\bin\??.exe |
|
93 sample.img </userinput> </p> <p> <b><i>Extracting a set of files with |
|
94 wildcard *</i></b> </p> <p>The READIMAGE tool provides the -x option |
|
95 to extract one or more files from a ROM or ROFS image, based on a |
|
96 pattern that matches the name of the file. A star sign(*) indicates |
|
97 to match zero or more instances of any character in a file name, within |
|
98 the directory. </p> <p>The command below extracts all the <filepath>.exe</filepath> files from the \sys\bin directory present in the <filepath>sample.img</filepath> file, into the current directory. </p> <p><userinput>readimage -x \sys\bin\*.exe sample.img</userinput> </p> <p>The command |
|
99 below extracts all the <filepath>.exe</filepath> files from the \sys\bin |
|
100 directory present in the <filepath>sample.img</filepath> file, into |
|
101 the C:\test location. </p> <p><userinput>readimage -x \sys\bin\*.exe |
|
102 -z C:\test sample.img</userinput> </p> <p>The command below extracts |
|
103 all the .dll files from the \sys\bin\ directory and its sub-directories |
|
104 present in the sample.img file, into the current directory. </p> <p><userinput>readimage -x \sys\bin\*.dll -r sample.img</userinput> </p> <p><b>Generating an IBY file from a SIS file</b> </p> <p>Run the |
|
105 following command to generate an <filepath>.iby</filepath> file from |
|
106 a <filepath>.sis</filepath> file: </p> <p><userinput>readimage -sis2iby |
|
107 [-tmpdir <path> -outdir <path>] <sisfile></userinput> </p> <p>The following command-line options are supported when generating |
|
108 an <filepath>.iby</filepath> file from a <filepath>.sis</filepath> file: </p> <table id="GUID-5033FF35-0597-54EF-BDCC-46D66591F629"> |
|
109 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
110 <thead> |
|
111 <row> |
|
112 <entry>Options</entry> |
|
113 <entry>Description</entry> |
|
114 </row> |
|
115 </thead> |
|
116 <tbody> |
|
117 <row> |
|
118 <entry><p> <codeph><sisfile></codeph> </p> </entry> |
|
119 <entry><p>Input <filepath>.sis</filepath> file. </p> </entry> |
|
120 </row> |
|
121 <row> |
|
122 <entry><p> <codeph> -sis2iby</codeph> </p> </entry> |
|
123 <entry><p>Used to generate <filepath>.iby</filepath> file for the |
|
124 given <filepath>.sis</filepath> file. </p> </entry> |
|
125 </row> |
|
126 <row> |
|
127 <entry><p> <codeph> -tmpdir <path></codeph> </p> </entry> |
|
128 <entry><p>Extracts contents of the <filepath>.sis</filepath> file |
|
129 to the specified directory. </p> </entry> |
|
130 </row> |
|
131 <row> |
|
132 <entry><p> <codeph>-outdir <path></codeph> </p> </entry> |
|
133 <entry><p>Generates <filepath>.iby</filepath> file in the specified |
|
134 directory. </p> </entry> |
|
135 </row> |
|
136 </tbody> |
|
137 </tgroup> |
|
138 </table> <p>To generate an <filepath>.iby</filepath> file from the |
|
139 given <filepath>.sis</filepath> file, READIMAGE performs the steps |
|
140 as follows: </p> <ol id="GUID-6E427F6F-712F-51F5-B6B5-B9B4970017A1"> |
|
141 <li id="GUID-459AE7C1-B254-5FD6-A574-306F847AD989"><p>Reports an error |
|
142 if the <filepath>.sis</filepath> file is invalid or missing. </p> </li> |
|
143 <li id="GUID-09E38B54-F6AD-5323-AD7D-FA1F5DCA58B2"><p>Extracts the |
|
144 contents of the <filepath>.sis</filepath> file into a specified directory, |
|
145 or the current directory if the path is not specified. A <filepath>.pkg</filepath> script file is extracted from the sis file. </p> </li> |
|
146 <li id="GUID-A1E4B1C5-1507-5809-B41C-4C26E12F77E8"><p>Creates an <filepath>.iby</filepath> file in the specified directory or the current directory |
|
147 based on the <filepath>.pkg</filepath> file. </p> </li> |
|
148 </ol> <p>The <filepath>.sis</filepath> file is created using the package |
|
149 (PKG) script file. A <filepath>.pkg</filepath> file is a text file |
|
150 containing statements that define the information needed by the installation |
|
151 (<filepath>.sis</filepath> ) file creation utility, MAKESIS. </p> <p>For more information about creating <filepath>.sis</filepath> file, |
|
152 see <xref href="GUID-4BDC9F63-83A1-53A5-91A0-B092AA821755.dita">MakeSIS</xref> Installation file generator syntax. For more information on the |
|
153 .pkg file format, see <xref href="GUID-6D6C54E2-66DA-5626-A75D-5597469D5BE0.dita">PKG File</xref> in |
|
154 the <xref href="GUID-2FC268F3-5EC2-40DB-B3EA-0E2D5C6EFCAD.dita">Symbian |
|
155 C++ Developer Library</xref>. </p> <p>READIMAGE extracts the <filepath>.pkg</filepath> file from the <filepath>.sis</filepath> file. It |
|
156 then uses the <filepath>.pkg</filepath> file as input to generate |
|
157 the <filepath>.iby</filepath> file. </p> <p><b><i>Languages and Package-header |
|
158 section</i></b> </p> <p>The details of Languages and Package-header |
|
159 sections are written in the <filepath>.iby</filepath> file as comments. </p> <ul> |
|
160 <li id="GUID-6998D038-C11F-5A1A-ABC8-8967438444AC"><p> <filepath>.pkg</filepath> file </p> <codeblock id="GUID-C35E5D70-C347-55C9-8612-C875D67380A0" xml:space="preserve">&EN |
|
161 # {"HelloWorld application"}, (0xe8000091), 1, 0, 0, TYPE=SA</codeblock> </li> |
|
162 <li id="GUID-3B4C9642-0774-5B1F-B5F2-4F7A6B001B6A"><p> <filepath>.iby</filepath> file </p> <codeblock id="GUID-EE292E70-9E4D-53E8-AF9D-0633DE89AE87" xml:space="preserve">// Generated IBY file for the package file: \dump\hwapp\hwapp.pkg |
|
163 // Languages: EN |
|
164 // Header: "HelloWorld application" (0xe8000091)</codeblock> </li> |
|
165 </ul> <p><b><i>Install-file section</i></b> </p> <p>In the Install-file |
|
166 section, the standard installation files, which are specified with |
|
167 the installation option <codeph>FF</codeph>, are written using the <codeph>FILE</codeph> or <codeph>DATA OBEY</codeph> file keywords. The <codeph>File</codeph> keyword is used if the file is an E32 image, Otherwise, |
|
168 the <codeph>Data</codeph> keyword is used. </p> <ul> |
|
169 <li id="GUID-466E2C48-C6A1-5AAA-9315-125FC9C4D9F0"><p> <filepath>.pkg</filepath> file </p> <codeblock id="GUID-5FF15257-A248-533A-BBED-5D517F1CB988" xml:space="preserve">"file0" - "!:\sys\bin\HelloWorld.exe", FF, VR |
|
170 "file1" - "!:\private\<process SID>\Apps\AGENDA\Ericsson.txt", FF, VR</codeblock> </li> |
|
171 <li id="GUID-FE0C0E53-65E7-55FB-A7A0-D268EE74A53B"><p> <filepath>.iby</filepath> file </p> <codeblock id="GUID-3BC88477-86B8-5019-B87D-BABDE6BB60F0" xml:space="preserve">file = "\test\dump\hwapp\file0" "\sys\bin\HelloWorld.exe" |
|
172 data = "\test\dump\hwapp\sis0\file1" "\private\<process SID>\Apps\AGENDA\Ericsson.txt"</codeblock> </li> |
|
173 </ul> <p><b><i>Embedded-SIS section</i></b> </p> <p>The details of |
|
174 the Embedded-SIS section are written using <codeph>#include</codeph> pre-processor directive. </p> <ul> |
|
175 <li id="GUID-1674C791-9BEF-5E21-90E9-04B4D7EEEFAB"><p> <filepath>.pkg</filepath> file </p> <codeblock id="GUID-0EED436A-74BF-5AC8-84EA-3325E2057F52" xml:space="preserve">@"sis0.sis", (0x101f7771) |
|
176 @"sis1.sis", (0x101f7773)</codeblock> </li> |
|
177 <li id="GUID-235D1AD1-2DE1-5414-97A7-2C6A4B6FDAA3"><p> <filepath>.iby</filepath> file </p> <codeblock id="GUID-DF10E57A-DE34-5914-A6B9-1D723F19DF4B" xml:space="preserve">#include "sis0.sis" |
|
178 #include "sis1.sis"</codeblock> </li> |
|
179 </ul> <p><b><i>Conditions-block section</i></b> </p> <p>In the Conditions-block |
|
180 section, the IF statements are written using the <codeph>#if - #else |
|
181 - #endif</codeph> pre-processor directive block. </p> <p>The condition-primitives |
|
182 and the functions in the <filepath>.pkg</filepath> file are written |
|
183 as pre-processor macros. </p> <p>The relational and logical operator |
|
184 keywords are written using the appropriate operators. </p> <ul> |
|
185 <li id="GUID-CD902082-FC13-5B1E-A316-2D0B289D9ECA"><p> <filepath>.pkg</filepath> file </p> <codeblock id="GUID-C21BA23D-3D71-56E0-8F6D-5A3448403D07" xml:space="preserve">;Display 2 options to the user |
|
186 ! ({"Option1", "Option1"}, {"Option2", "Option2"}) |
|
187 ;Conditional installation |
|
188 IF option1 |
|
189 "file0" - "!:\private\10000005\import\InstTest\option1.txt"; |
|
190 ENDIF |
|
191 IF option2 |
|
192 "file0" - "!:\private\10000005\import\InstTest\option2.txt"; |
|
193 ENDIF |
|
194 ;Conditional installation |
|
195 IF (MANUFACTURER) = (1) |
|
196 "file1" - "!:\sys\bin\HelloWorld.exe" |
|
197 ELSEIF (MANUFACTURER) = (4) |
|
198 "file1" - "!:\sys\bin\HelloWorld1.exe" |
|
199 ELSE |
|
200 "file1" - "!:\sys\bin\HelloWorld2.exe" |
|
201 ENDIF |
|
202 |
|
203 </codeblock> </li> |
|
204 <li id="GUID-723E919D-4A09-5923-99EC-5B1BBD7D1C08"><p> <filepath>.iby</filepath> file </p> <codeblock id="GUID-A7D26F78-0287-52F9-B1DC-13AD7EEF9594" xml:space="preserve">//Install Options: "OPTION1" "OPTION1" "OPTION2" "OPTION2" |
|
205 #if defined (option1) |
|
206 data = "s:\test\hwapp\file0" |
|
207 "\private\10000005\import\InstTest\option1.txt"; |
|
208 #endif |
|
209 #if defined (option2) |
|
210 data = "s:\test\hwapp\file0" |
|
211 "\private\10000005\import\InstTest\option2.txt"; |
|
212 #endif |
|
213 |
|
214 #if (MANUFACTURER) = (1) |
|
215 file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld.exe" |
|
216 #elseif (MANUFACTURER) = (4) |
|
217 file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld1.exe" |
|
218 #else |
|
219 file = "s:\test\hwapp\file1" "\sys\bin\HelloWorld2.exe" |
|
220 #endif</codeblock> </li> |
|
221 </ul> <p> <b>Note:</b> Using the <filepath>.iby</filepath> file with |
|
222 the condition-block statements for the creation of ROM and ROFS images |
|
223 needs appropriate macro definitions. For the preceding examples, the |
|
224 macros are defined as follows: </p> <codeblock id="GUID-B79B1372-3B2D-5A7E-9A7C-568302CC7D3F" xml:space="preserve">#define option1 //selecting option1 block |
|
225 #define MANUFACTURER 4 //selecting second conditional block</codeblock> </section> |
|
226 </conbody></concept> |