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-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD" xml:lang="en"><title>evalid |
|
13 Command Syntax</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section><title>Purpose</title> <p> evalid compares two files, or two trees |
|
15 of files, ignoring insignificant differences in some types of files. You can |
|
16 use it to check if the behaviour and compatibility of a build has changed, |
|
17 without having to run complex BC (Binary Compatibility) checking tools or |
|
18 regression tests. </p> <p>Typically, evalid is useful when you make changes |
|
19 in the source code or in the build environment, which do not affect the built |
|
20 files. Such source changes include adding comments, or configured code that |
|
21 should not be built in the configuration that you are testing. You can use |
|
22 evalid to compare new and old builds, and check for differences. </p> <p>Standard |
|
23 diff tools would typically flag environment information, such as time stamps, |
|
24 as differences, whereas evalid has better comparison rules that allows it |
|
25 to ignore insignificant differences. </p> <p>You can use evalid in two ways: |
|
26 to directly compare files, or to generate a hash (using the MD5 algorithm) |
|
27 of files, and then later compare the hashes. The second method can be more |
|
28 convenient, as it does not require both builds to be available when the comparison |
|
29 is done. </p> </section> |
|
30 <section id="GUID-478305DC-1A5E-5FAB-841A-5B40A4A3443A"><title>Usage</title> <p> evalid |
|
31 is a command-line tool, delivered in the <filepath>epoc32\tools</filepath> directory |
|
32 of the Symbian platform kit. You can invoke it with various options, depending |
|
33 on the task you want to perform. This section describes these options. </p> <p>The |
|
34 results from running the tool are written by default to a log file <filepath>evalid.lis</filepath>. |
|
35 You can change the log file, or choose to log to screen, using the <xref href="GUID-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD.dita#GUID-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD/GUID-B4AA5F08-7AEF-5AFC-B316-ADD972BF0A2D">Log options</xref> flags. The meanings of the log messages are described |
|
36 in the <xref href="GUID-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD.dita#GUID-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD/GUID-80209D4B-081E-5C93-ADF4-FB968558B4B3">Log |
|
37 messages</xref> section. The tool terminates with an error message if the |
|
38 files or directories specified as input arguments do not exist. </p> <p><b>Directly |
|
39 compare two files</b> </p> <p><userinput>evalid <parmname>[log-options]</parmname> <cmdname>file1</cmdname> <cmdname>file2</cmdname> </userinput> </p> <p>This compares <varname>file1</varname> against <varname>file2</varname>. </p> <p><b> Recursively |
|
40 compare two directory trees </b> </p> <p><userinput>evalid <parmname>[log-options]</parmname> <cmdname>directory1</cmdname> <cmdname>directory2</cmdname> </userinput> </p> <p>This compares each file in the directory tree <varname>directory1</varname> against |
|
41 the corresponding file in the directory tree <varname>directory2</varname>. </p> <p><b>Recursively |
|
42 create MD5 hashes for a directory tree</b> </p> <p><userinput>evalid <parmname>[log-options]</parmname> <parmname>-g</parmname> [<parmname>-x |
|
43 regular-expression</parmname>] [<parmname>-I regular-expression</parmname>] <cmdname>directory1</cmdname> <cmdname>file1</cmdname> </userinput> </p> <p>Option <codeph>-g</codeph> creates an MD5 hash for |
|
44 each file in <varname>directory1</varname>, and stores this data in the file <varname>file1</varname>. </p> <p>You |
|
45 can then compare two directories by passing their hash data files to evalid |
|
46 using the <codeph>-m</codeph> option, described below. </p> <p>You can limit |
|
47 the files that are processed using these filter options: </p> <table id="GUID-7364348F-D590-51A0-A5EE-D81D4877CDBD"> |
|
48 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
49 <tbody> |
|
50 <row> |
|
51 <entry><p> <codeph>-x</codeph> <varname>regular-expression</varname> </p> </entry> |
|
52 <entry><p>Exclude files with names that match the specified Perl regular expression. |
|
53 Syntax for Perl regular expressions can be found at <xref href="http://www.perl.com/pub/q/documentation" scope="external">http://www.perl.com</xref>. </p> </entry> |
|
54 </row> |
|
55 <row> |
|
56 <entry><p> <codeph>-I</codeph> <varname>regular-expression</varname> </p> </entry> |
|
57 <entry><p>Include only files with names that match the specified Perl regular |
|
58 expression. </p> </entry> |
|
59 </row> |
|
60 </tbody> |
|
61 </tgroup> |
|
62 </table> <p>Inclusions take precedence over exclusions if both expressions |
|
63 match. </p> <p><b>Create MD5 hashes of specified files</b> </p> <p><userinput>evalid <parmname>[log-options]</parmname> <parmname>-f</parmname> [<parmname>-x regular-expression</parmname>] [<parmname>-I |
|
64 regular-expression</parmname>] <cmdname>listfile</cmdname> <cmdname>directory1</cmdname> <cmdname>file1</cmdname> </userinput> </p> <p>Option <codeph>-f</codeph> creates an MD5 hash for each file listed in the file <varname>listfile</varname>, |
|
65 and stores this data in the file <varname>file1</varname>. </p> <p>The <varname>listfile</varname> must |
|
66 contain a list of files, one per line. File paths should be specified relative |
|
67 to <varname>directory1</varname>, and must not start with a directory separator |
|
68 (<filepath>\</filepath>). </p> <p>You can limit the files that are processed |
|
69 using the <codeph>-x</codeph> and <codeph>-I</codeph> options, as described |
|
70 above for the <codeph>-g</codeph> option. </p> <p><b>Compare two MD5 hash |
|
71 data files</b> </p> <p><userinput>evalid <parmname>[log-options]</parmname> <parmname>-m</parmname> <cmdname>file1</cmdname> <cmdname>file2</cmdname> </userinput> </p> <p>Option <codeph>-m</codeph> compares the MD5 hashes |
|
72 in <varname>file1</varname> (created using option <codeph>-g</codeph> or <codeph>-f</codeph>) |
|
73 against those in <varname>file2</varname>. </p> <p><b>Compare two MD5 hash |
|
74 data files, and update directory</b> </p> <p><userinput>evalid <parmname>[log-options]</parmname> <parmname>-u</parmname> <cmdname>file1</cmdname> <cmdname>file2</cmdname> </userinput> </p> <p>Option <codeph>-u</codeph> is |
|
75 an alternative to <codeph>-m</codeph>. It creates batch files that you can |
|
76 run to change the files defined by <varname>file1</varname> to be the same |
|
77 as the files defined by <varname>file2</varname>. </p> <p>The output batch |
|
78 file <filepath>del_<file1>_to_<file2>.bat</filepath> deletes files that |
|
79 are defined in <varname>file1</varname> but not in <varname>file2</varname>. </p> <p>The |
|
80 output batch file <filepath>zip_<file1>_to_<file2>.bat</filepath> creates |
|
81 a zip of the files that are defined in <varname>file2</varname> but not in <varname>file1</varname>, |
|
82 and of files that are defined in both, but are different. </p> <p><b>Create |
|
83 a dump of descriptive information required for analysis</b> </p> <p>As part |
|
84 of MD5 generation, the tool extracts descriptive information about the files |
|
85 being compared, and uses it in its comparisons. Creating a dump file of this |
|
86 descriptive information, helps in the detailed analysis of significant differences |
|
87 between the two files. It also helps in troubleshooting, if the tool fails |
|
88 to list all the significant differences between the two files. The following |
|
89 is the syntax to creating a dump file of the descriptive information: </p> <p><userinput>evalid <parmname>[log-options]</parmname> <parmname>-f |
|
90 | -g</parmname> [<parmname>-x regular-expression</parmname>] |
|
91 [<parmname>-I regular-expression</parmname>] [<parmname>-d |
|
92 dump-directory</parmname>] <cmdname>listfile</cmdname> <cmdname>directory1</cmdname> <cmdname>file1</cmdname> </userinput> </p> <p>Where, |
|
93 the <codeph>-d</codeph> option creates a dump file for each of those files |
|
94 listed in <varname>listfile</varname> or <varname>directory1</varname> using |
|
95 the <codeph>-f</codeph> or <codeph>-g</codeph> MD5 generation options. The |
|
96 dump files are placed in the <varname>dump directory</varname> with |
|
97 the directory structure that is similar to the input directory structure. </p> <p>For |
|
98 example, consider the following DLLs which are two different builds of the |
|
99 same DLL, but are significantly different in content: </p> <p> <filepath>D:\epoc32\release\armv5\urel\mycomponent.dll</filepath> </p> <p> <filepath>E:\epoc32\release\armv5\urel\mycomponent.dll</filepath> </p> <p>Using the |
|
100 following commands to dump files and generate MD5 hash for both the DLLs: </p> <p><userinput>evalid |
|
101 -d \buildone -g epoc32 buildone.md5</userinput> </p> <p><userinput>evalid |
|
102 -d \buildtwo -g epoc32 buildtwo.md5</userinput> </p> <p>Apart from generating |
|
103 the two <filepath>.md5</filepath> files, the commands listed above also generate |
|
104 the following dump files with the directory structure: </p> <p> <filepath>D:\buildone\epoc32\release\armv5\urel\mycomponent.dll</filepath> </p> <p> <filepath>E:\buildtwo\epoc32\release\armv5\urel\mycomponent.dll</filepath> </p> <p>Both |
|
105 the files listed above are text files containing descriptive information about |
|
106 the two different builds of <filepath>mycomponent.dll</filepath>. A text compare |
|
107 between these two dump files would list differences between the two builds |
|
108 of <filepath>mycomponent.dll</filepath> that evalid views as significant. |
|
109 In the case of comparing two directory trees, a recursive comparison between |
|
110 the two dump directories (<filepath>buildone</filepath> and <filepath>buildtwo</filepath>) |
|
111 using Beyond Compare would list the differences between the directories. </p> <p> <b>Note:</b> If |
|
112 the evalid tool decides to examine an input file without any further processing, |
|
113 then the generated MD5 hash is based directly on the input file. Using <codeph>-d</codeph> option |
|
114 in such situations, copies the input file as it is to the dump directory. |
|
115 Comparing the two dump directories containing a copy of the input files, is |
|
116 similar to comparing the MD5 files based on the input files, using evalid. </p> <p id="GUID-B4AA5F08-7AEF-5AFC-B316-ADD972BF0A2D"><b>Log options</b> </p> <p>The <varname>log-options</varname> options |
|
117 control how the tool outputs its results: </p> <table id="GUID-1EC54E5C-85E7-5AF7-B00C-F337E29C9D57"> |
|
118 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
119 <tbody> |
|
120 <row> |
|
121 <entry><p> <codeph> -v</codeph> </p> </entry> |
|
122 <entry><p>Provide verbose information about failed comparisons. </p> <p>This |
|
123 has no effect on MD5 operations. </p> </entry> |
|
124 </row> |
|
125 <row> |
|
126 <entry><p> <codeph>-c</codeph> </p> </entry> |
|
127 <entry><p>Print results to standard out (i.e. the screen). </p> </entry> |
|
128 </row> |
|
129 <row> |
|
130 <entry><p> <codeph>-l <logfile></codeph> </p> </entry> |
|
131 <entry><p>Append results to specified file. </p> <p>This has no effect when |
|
132 used with <codeph>-u</codeph>. </p> </entry> |
|
133 </row> |
|
134 </tbody> |
|
135 </tgroup> |
|
136 </table> <p>By default, output is written to the file <filepath>evalid.lis</filepath>. </p> <p><b> File |
|
137 and directory argument shorthand</b> </p> <p>Note that you can use the following |
|
138 shorthand in file and directory arguments: </p> <p> <codeph>evalid file1 dir2</codeph> is |
|
139 equivalent to <codeph>evalid file1 dir2\file1</codeph>. </p> <p> <codeph>evalid |
|
140 dir1 file1</codeph> is equivalent to <codeph>evalid dir1\file1 |
|
141 file1</codeph>. </p> </section> |
|
142 <section id="GUID-80209D4B-081E-5C93-ADF4-FB968558B4B3"><title>Log messages</title> <p> evalid |
|
143 reports the result of each file comparison that it performs. </p> <p>For example, |
|
144 in a direct comparison, the meaning of these messages are as follows: </p> <table id="GUID-4B5D8D0A-145A-5CBB-B07E-2A6B969AE071"> |
|
145 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
146 <tbody> |
|
147 <row> |
|
148 <entry><p> <b>Message type</b> </p> </entry> |
|
149 <entry><p> <b>Explanation</b> </p> </entry> |
|
150 </row> |
|
151 <row> |
|
152 <entry><p> <codeph> OK: ... (identical) </codeph> </p> </entry> |
|
153 <entry><p>Files are exactly the same. For example: </p> <codeblock id="GUID-3458E2BF-A9AE-50B4-94D8-9B8727B39C6E" xml:space="preserve">OK: epoc32\release\armv5\urel\XMLDOM.DLL and epoc32_master\release\armv5\urel\XMLDOM.DLL (identical)</codeblock> </entry> |
|
154 </row> |
|
155 <row> |
|
156 <entry><p> <codeph> OK: ... (<type>)</codeph> </p> </entry> |
|
157 <entry><p>The files are different, but the comparison rules for the file type |
|
158 indicate that the difference is not significant. For example: </p> <codeblock id="GUID-68819FCD-1FA0-52D6-8FD1-11840D302D09" xml:space="preserve">OK: epoc32\release\armv5\urel\cprov.exe and epoc32_master\release\armv5\urel\cprov.exe (E32 EXE) </codeblock> </entry> |
|
159 </row> |
|
160 <row> |
|
161 <entry><p> <codeph>MISSING:...</codeph> </p> </entry> |
|
162 <entry><p>A file that is present in the first tree is not present in the second. |
|
163 For example: </p> <codeblock id="GUID-1542FC15-3819-56D8-A1B3-94C0035729F4" xml:space="preserve">MISSING: epoc32_master\release\armv5\urel\alink.dll </codeblock> <p>Note |
|
164 that evalid does not check to see if files in the second tree are present |
|
165 in the first. </p> </entry> |
|
166 </row> |
|
167 <row> |
|
168 <entry><p> <codeph>FAILED:... </codeph> </p> </entry> |
|
169 <entry><p>There is a significant difference between the files. If evalid does |
|
170 not know the type of the files being compared, it does a binary comparison, |
|
171 so any time stamp differences cause it to report a failure. </p> <p>For example: </p> <codeblock id="GUID-3CD93458-14F8-5A36-861C-FC6B7453FC6C" xml:space="preserve">FAILED: epoc32\release\armv5\urel\ASN1.DLL and epoc32_master\release\armv5\urel\ASN1.DLL (Compressed E32 DLL)</codeblock> </entry> |
|
172 </row> |
|
173 </tbody> |
|
174 </tgroup> |
|
175 </table> <p>For an MD5 comparison, the meaning of these messages is as follows: </p> <table id="GUID-489A4DD4-38D9-5A4A-8DD0-EBC66300A203"> |
|
176 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
177 <tbody> |
|
178 <row> |
|
179 <entry><p> <b>Message type</b> </p> </entry> |
|
180 <entry><p> <b>Explanation</b> </p> </entry> |
|
181 </row> |
|
182 <row> |
|
183 <entry><p> <codeph>Passed </codeph> </p> </entry> |
|
184 <entry><p>Files have no significant differences. </p> </entry> |
|
185 </row> |
|
186 <row> |
|
187 <entry><p> <codeph>Failed</codeph> </p> </entry> |
|
188 <entry><p>There is a significant difference between the files. </p> </entry> |
|
189 </row> |
|
190 <row> |
|
191 <entry><p> <codeph>Missing Left</codeph> </p> </entry> |
|
192 <entry><p>A file listed in the first MD5 file is not present in the second. </p> </entry> |
|
193 </row> |
|
194 <row> |
|
195 <entry><p> <codeph>Missing Right</codeph> </p> </entry> |
|
196 <entry><p>A file listed in the second MD5 file is not present in the first. </p> </entry> |
|
197 </row> |
|
198 </tbody> |
|
199 </tgroup> |
|
200 </table> </section> |
|
201 <section id="GUID-153BF974-534C-58E0-A6E7-CF9AEEFD489A"><title>Recognized |
|
202 file types</title> <p>These are the types of files for which evalid has special |
|
203 support for finding and ignoring insignificant differences: </p> <ul> |
|
204 <li id="GUID-2BCA1EC9-2C22-5FF4-90DA-AECB2B7E94FC"><p>ELF format </p> </li> |
|
205 <li id="GUID-C9C638B6-A697-5BFD-BD6F-D2DAD9EB78BE"><p>E32 Image (Symbian platform |
|
206 executables) </p> </li> |
|
207 <li id="GUID-649F98D8-01A6-53A4-A978-65FFA37ED81E"><p>EPOC Permanent File |
|
208 Store </p> </li> |
|
209 <li id="GUID-0E343A53-DF61-5F2C-961E-AB43A2F9FBCA"><p>MAP files from the GNU |
|
210 Linker, CodeWarrior and RVCT </p> </li> |
|
211 <li id="GUID-2E9B3FE7-0D67-5369-AEB7-81AED46B5F3F"><p>Microsoft Compiled HTML |
|
212 Help </p> </li> |
|
213 <li id="GUID-DD8E4C47-0E33-5366-A362-414DE54B1247"><p>Microsoft PE COFF (Windows/MS-DOS |
|
214 executables, object files, and import and static libraries) </p> <p>Note that |
|
215 comparisons of such files requires that Microsoft's DUMPBIN tool from Microsoft |
|
216 Visual Studio v6 is installed. </p> </li> |
|
217 <li id="GUID-4FA0265A-1448-52CC-9D7F-2210BC340428"><p>Pre-processor (<filepath>cpp.exe</filepath>) |
|
218 output </p> </li> |
|
219 <li id="GUID-31B3FDCF-0B55-568F-A184-2253825AA4A9"><p>SGML (including XML |
|
220 and HTML) </p> </li> |
|
221 <li id="GUID-2F3CC859-AAC1-5A32-A10D-D258A03E7EAB"><p>ZIP </p> </li> |
|
222 </ul> </section> |
|
223 </conbody></concept> |
|