<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD" xml:lang="en"><title>evalid

Command Syntax</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Purpose</title> <p> evalid compares two files, or two trees

of files, ignoring insignificant differences in some types of files. You can

use it to check if the behaviour and compatibility of a build has changed,

without having to run complex BC (Binary Compatibility) checking tools or

regression tests. </p> <p>Typically, evalid is useful when you make changes

in the source code or in the build environment, which do not affect the built

files. Such source changes include adding comments, or configured code that

should not be built in the configuration that you are testing. You can use

evalid to compare new and old builds, and check for differences. </p> <p>Standard

diff tools would typically flag environment information, such as time stamps,

as differences, whereas evalid has better comparison rules that allows it

to ignore insignificant differences. </p> <p>You can use evalid in two ways:

to directly compare files, or to generate a hash (using the MD5 algorithm)

of files, and then later compare the hashes. The second method can be more

convenient, as it does not require both builds to be available when the comparison

is done. </p> </section>

<section id="GUID-478305DC-1A5E-5FAB-841A-5B40A4A3443A"><title>Usage</title> <p> evalid

is a command-line tool, delivered in the <filepath>epoc32\tools</filepath> directory

of the Symbian platform kit. You can invoke it with various options, depending

on the task you want to perform. This section describes these options. </p> <p>The

results from running the tool are written by default to a log file <filepath>evalid.lis</filepath>.

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

in the <xref href="GUID-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD.dita#GUID-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD/GUID-80209D4B-081E-5C93-ADF4-FB968558B4B3">Log

messages</xref> section. The tool terminates with an error message if the

files or directories specified as input arguments do not exist. </p> <p><b>Directly

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

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

the corresponding file in the directory tree <varname>directory2</varname>. </p> <p><b>Recursively

create MD5 hashes for a directory tree</b> </p> <p><userinput>evalid <parmname>[log-options]</parmname> <parmname>-g</parmname> [<parmname>-x

             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

each file in <varname>directory1</varname>, and stores this data in the file <varname>file1</varname>. </p> <p>You

can then compare two directories by passing their hash data files to evalid

using the <codeph>-m</codeph> option, described below. </p> <p>You can limit

the files that are processed using these filter options: </p> <table id="GUID-7364348F-D590-51A0-A5EE-D81D4877CDBD">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <codeph>-x</codeph>  <varname>regular-expression</varname>  </p> </entry>

<entry><p>Exclude files with names that match the specified Perl regular expression.

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>

</row>

<row>

<entry><p> <codeph>-I</codeph>  <varname>regular-expression</varname>  </p> </entry>

<entry><p>Include only files with names that match the specified Perl regular

expression. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>Inclusions take precedence over exclusions if both expressions

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            

 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>,

and stores this data in the file <varname>file1</varname>. </p> <p>The <varname>listfile</varname> must

contain a list of files, one per line. File paths should be specified relative

to <varname>directory1</varname>, and must not start with a directory separator

(<filepath>\</filepath>). </p> <p>You can limit the files that are processed

using the <codeph>-x</codeph> and <codeph>-I</codeph> options, as described

above for the <codeph>-g</codeph> option. </p> <p><b>Compare two MD5 hash

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

in <varname>file1</varname> (created using option <codeph>-g</codeph> or <codeph>-f</codeph>)

against those in <varname>file2</varname>. </p> <p><b>Compare two MD5 hash

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

an alternative to <codeph>-m</codeph>. It creates batch files that you can

run to change the files defined by <varname>file1</varname> to be the same

as the files defined by <varname>file2</varname>. </p> <p>The output batch

file <filepath>del_&lt;file1&gt;_to_&lt;file2&gt;.bat</filepath> deletes files that

are defined in <varname>file1</varname> but not in <varname>file2</varname>. </p> <p>The

output batch file <filepath>zip_&lt;file1&gt;_to_&lt;file2&gt;.bat</filepath> creates

a zip of the files that are defined in <varname>file2</varname> but not in <varname>file1</varname>,

and of files that are defined in both, but are different. </p> <p><b>Create

a dump of descriptive information required for analysis</b> </p> <p>As part

of MD5 generation, the tool extracts descriptive information about the files

being compared, and uses it in its comparisons. Creating a dump file of this

descriptive information, helps in the detailed analysis of significant differences

between the two files. It also helps in troubleshooting, if the tool fails

to list all the significant differences between the two files. The following

is the syntax to creating a dump file of the descriptive information: </p> <p><userinput>evalid <parmname>[log-options]</parmname>  <parmname>-f

|              -g</parmname> [<parmname>-x              regular-expression</parmname>]

[<parmname>-I              regular-expression</parmname>] [<parmname>-d  

           dump-directory</parmname>] <cmdname>listfile</cmdname> <cmdname>directory1</cmdname> <cmdname>file1</cmdname> </userinput> </p> <p>Where,

the <codeph>-d</codeph> option creates a dump file for each of those files

listed in <varname>listfile</varname> or <varname>directory1</varname> using

the <codeph>-f</codeph> or <codeph>-g</codeph> MD5 generation options. The

dump files are placed in the <varname>dump              directory</varname> with

the directory structure that is similar to the input directory structure. </p> <p>For

example, consider the following DLLs which are two different builds of the

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

following commands to dump files and generate MD5 hash for both the DLLs: </p> <p><userinput>evalid

-d \buildone -g epoc32 buildone.md5</userinput> </p> <p><userinput>evalid

-d \buildtwo -g epoc32 buildtwo.md5</userinput> </p> <p>Apart from generating

the two <filepath>.md5</filepath> files, the commands listed above also generate

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

the files listed above are text files containing descriptive information about

the two different builds of <filepath>mycomponent.dll</filepath>. A text compare

between these two dump files would list differences between the two builds

of <filepath>mycomponent.dll</filepath> that evalid views as significant.

In the case of comparing two directory trees, a recursive comparison between

the two dump directories (<filepath>buildone</filepath> and <filepath>buildtwo</filepath>)

using Beyond Compare would list the differences between the directories. </p> <p> <b>Note:</b> If

the evalid tool decides to examine an input file without any further processing,

then the generated MD5 hash is based directly on the input file. Using <codeph>-d</codeph> option

in such situations, copies the input file as it is to the dump directory.

Comparing the two dump directories containing a copy of the input files, is

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

control how the tool outputs its results: </p> <table id="GUID-1EC54E5C-85E7-5AF7-B00C-F337E29C9D57">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <codeph> -v</codeph>  </p> </entry>

<entry><p>Provide verbose information about failed comparisons. </p> <p>This

has no effect on MD5 operations. </p> </entry>

</row>

<row>

<entry><p> <codeph>-c</codeph>  </p> </entry>

<entry><p>Print results to standard out (i.e. the screen). </p> </entry>

</row>

<row>

<entry><p> <codeph>-l &lt;logfile&gt;</codeph>  </p> </entry>

<entry><p>Append results to specified file. </p> <p>This has no effect when

used with <codeph>-u</codeph>. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>By default, output is written to the file <filepath>evalid.lis</filepath>. </p> <p><b> File

and directory argument shorthand</b> </p> <p>Note that you can use the following

shorthand in file and directory arguments: </p> <p> <codeph>evalid file1 dir2</codeph> is

equivalent to <codeph>evalid file1              dir2\file1</codeph>. </p> <p> <codeph>evalid

dir1 file1</codeph> is equivalent to <codeph>evalid              dir1\file1

file1</codeph>. </p> </section>

<section id="GUID-80209D4B-081E-5C93-ADF4-FB968558B4B3"><title>Log messages</title> <p> evalid

reports the result of each file comparison that it performs. </p> <p>For example,

in a direct comparison, the meaning of these messages are as follows: </p> <table id="GUID-4B5D8D0A-145A-5CBB-B07E-2A6B969AE071">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Message type</b>  </p> </entry>

<entry><p> <b>Explanation</b>  </p> </entry>

</row>

<row>

<entry><p> <codeph> OK: ... (identical) </codeph>  </p> </entry>

<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>

</row>

<row>

<entry><p> <codeph> OK: ... (&lt;type&gt;)</codeph>  </p> </entry>

<entry><p>The files are different, but the comparison rules for the file type

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>

</row>

<row>

<entry><p> <codeph>MISSING:...</codeph>  </p> </entry>

<entry><p>A file that is present in the first tree is not present in the second.

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

that evalid does not check to see if files in the second tree are present

in the first. </p> </entry>

</row>

<row>

<entry><p> <codeph>FAILED:... </codeph>  </p> </entry>

<entry><p>There is a significant difference between the files. If evalid does

not know the type of the files being compared, it does a binary comparison,

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>

</row>

</tbody>

</tgroup>

</table> <p>For an MD5 comparison, the meaning of these messages is as follows: </p> <table id="GUID-489A4DD4-38D9-5A4A-8DD0-EBC66300A203">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Message type</b>  </p> </entry>

<entry><p> <b>Explanation</b>  </p> </entry>

</row>

<row>

<entry><p> <codeph>Passed </codeph>  </p> </entry>

<entry><p>Files have no significant differences. </p> </entry>

</row>

<row>

<entry><p> <codeph>Failed</codeph>  </p> </entry>

<entry><p>There is a significant difference between the files. </p> </entry>

</row>

<row>

<entry><p> <codeph>Missing Left</codeph>  </p> </entry>

<entry><p>A file listed in the first MD5 file is not present in the second. </p> </entry>

</row>

<row>

<entry><p> <codeph>Missing Right</codeph>  </p> </entry>

<entry><p>A file listed in the second MD5 file is not present in the first. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-153BF974-534C-58E0-A6E7-CF9AEEFD489A"><title>Recognized

file types</title> <p>These are the types of files for which evalid has special

support for finding and ignoring insignificant differences: </p> <ul>

<li id="GUID-2BCA1EC9-2C22-5FF4-90DA-AECB2B7E94FC"><p>ELF format </p> </li>

<li id="GUID-C9C638B6-A697-5BFD-BD6F-D2DAD9EB78BE"><p>E32 Image (Symbian platform

executables) </p> </li>

<li id="GUID-649F98D8-01A6-53A4-A978-65FFA37ED81E"><p>EPOC Permanent File

Store </p> </li>

<li id="GUID-0E343A53-DF61-5F2C-961E-AB43A2F9FBCA"><p>MAP files from the GNU

Linker, CodeWarrior and RVCT </p> </li>

<li id="GUID-2E9B3FE7-0D67-5369-AEB7-81AED46B5F3F"><p>Microsoft Compiled HTML

Help </p> </li>

<li id="GUID-DD8E4C47-0E33-5366-A362-414DE54B1247"><p>Microsoft PE COFF (Windows/MS-DOS

executables, object files, and import and static libraries) </p> <p>Note that

comparisons of such files requires that Microsoft's DUMPBIN tool from Microsoft

Visual Studio v6 is installed. </p> </li>

<li id="GUID-4FA0265A-1448-52CC-9D7F-2210BC340428"><p>Pre-processor (<filepath>cpp.exe</filepath>)

output </p> </li>

<li id="GUID-31B3FDCF-0B55-568F-A184-2253825AA4A9"><p>SGML (including XML

and HTML) </p> </li>

<li id="GUID-2F3CC859-AAC1-5A32-A10D-D258A03E7EAB"><p>ZIP </p> </li>

</ul> </section>