evalid -Command Syntax

Purpose

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.

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.

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.

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.

Usage

evalid -is a command-line tool, delivered in the epoc32\tools 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.

The -results from running the tool are written by default to a log file evalid.lis. -You can change the log file, or choose to log to screen, using the Log options flags. The meanings of the log messages are described -in the Log -messages section. The tool terminates with an error message if the -files or directories specified as input arguments do not exist.

Directly -compare two files

evalid [log-options] file1 file2

This compares file1 against file2.

Recursively -compare two directory trees

evalid [log-options] directory1 directory2

This compares each file in the directory tree directory1 against -the corresponding file in the directory tree directory2.

Recursively -create MD5 hashes for a directory tree

evalid [log-options] -g [-x - regular-expression] [-I regular-expression] directory1 file1

Option -g creates an MD5 hash for -each file in directory1, and stores this data in the file file1.

You -can then compare two directories by passing their hash data files to evalid -using the -m option, described below.

You can limit -the files that are processed using these filter options:

- - - -

-x regular-expression

Exclude files with names that match the specified Perl regular expression. -Syntax for Perl regular expressions can be found at http://www.perl.com.

- - -

-I regular-expression

Include only files with names that match the specified Perl regular -expression.

- - - -

Inclusions take precedence over exclusions if both expressions -match.

Create MD5 hashes of specified files

evalid [log-options] -f [-x regular-expression] [-I - regular-expression] listfile directory1 file1

Option -f creates an MD5 hash for each file listed in the file listfile, -and stores this data in the file file1.

The listfile must -contain a list of files, one per line. File paths should be specified relative -to directory1, and must not start with a directory separator -(\).

You can limit the files that are processed -using the -x and -I options, as described -above for the -g option.

Compare two MD5 hash -data files

evalid [log-options] -m file1 file2

Option -m compares the MD5 hashes -in file1 (created using option -g or -f) -against those in file2.

Compare two MD5 hash -data files, and update directory

evalid [log-options] -u file1 file2

Option -u is -an alternative to -m. It creates batch files that you can -run to change the files defined by file1 to be the same -as the files defined by file2.

The output batch -file del_<file1>_to_<file2>.bat deletes files that -are defined in file1 but not in file2.

The -output batch file zip_<file1>_to_<file2>.bat creates -a zip of the files that are defined in file2 but not in file1, -and of files that are defined in both, but are different.

Create -a dump of descriptive information required for analysis

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:

evalid [log-options] -f -| -g [-x regular-expression] -[-I regular-expression] [-d - dump-directory] listfile directory1 file1

Where, -the -d option creates a dump file for each of those files -listed in listfile or directory1 using -the -f or -g MD5 generation options. The -dump files are placed in the dump directory with -the directory structure that is similar to the input directory structure.

For -example, consider the following DLLs which are two different builds of the -same DLL, but are significantly different in content:

D:\epoc32\release\armv5\urel\mycomponent.dll

E:\epoc32\release\armv5\urel\mycomponent.dll

Using the -following commands to dump files and generate MD5 hash for both the DLLs:

evalid --d \buildone -g epoc32 buildone.md5

evalid --d \buildtwo -g epoc32 buildtwo.md5

Apart from generating -the two .md5 files, the commands listed above also generate -the following dump files with the directory structure:

D:\buildone\epoc32\release\armv5\urel\mycomponent.dll

E:\buildtwo\epoc32\release\armv5\urel\mycomponent.dll

Both -the files listed above are text files containing descriptive information about -the two different builds of mycomponent.dll. A text compare -between these two dump files would list differences between the two builds -of mycomponent.dll that evalid views as significant. -In the case of comparing two directory trees, a recursive comparison between -the two dump directories (buildone and buildtwo) -using Beyond Compare would list the differences between the directories.

Note: 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 -d 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.

Log options

The log-options options -control how the tool outputs its results:

- - - -

-v

Provide verbose information about failed comparisons.

This -has no effect on MD5 operations.

- - -

-c

Print results to standard out (i.e. the screen).

- - -

-l <logfile>

Append results to specified file.

This has no effect when -used with -u.

- - - -

By default, output is written to the file evalid.lis.

File -and directory argument shorthand

Note that you can use the following -shorthand in file and directory arguments:

evalid file1 dir2 is -equivalent to evalid file1 dir2\file1.

evalid -dir1 file1 is equivalent to evalid dir1\file1 -file1.

Log messages

evalid -reports the result of each file comparison that it performs.

For example, -in a direct comparison, the meaning of these messages are as follows:

- - - -

Message type

Explanation

- - -

OK: ... (identical)

Files are exactly the same. For example:

OK: epoc32\release\armv5\urel\XMLDOM.DLL and epoc32_master\release\armv5\urel\XMLDOM.DLL (identical) - - -

OK: ... (<type>)

The files are different, but the comparison rules for the file type -indicate that the difference is not significant. For example:

OK: epoc32\release\armv5\urel\cprov.exe and epoc32_master\release\armv5\urel\cprov.exe (E32 EXE) - - -

MISSING:...

A file that is present in the first tree is not present in the second. -For example:

MISSING: epoc32_master\release\armv5\urel\alink.dll

Note -that evalid does not check to see if files in the second tree are present -in the first.

- - -

FAILED:...

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.

For example:

FAILED: epoc32\release\armv5\urel\ASN1.DLL and epoc32_master\release\armv5\urel\ASN1.DLL (Compressed E32 DLL) - - - -

For an MD5 comparison, the meaning of these messages is as follows:

- - - -

Message type

Explanation

- - -

Passed

Files have no significant differences.

- - -

Failed

There is a significant difference between the files.

- - -

Missing Left

A file listed in the first MD5 file is not present in the second.

- - -

Missing Right

A file listed in the second MD5 file is not present in the first.

- - - -

Recognized -file types

These are the types of files for which evalid has special -support for finding and ignoring insignificant differences:

ELF format
E32 Image (Symbian platform -executables)
EPOC Permanent File -Store
MAP files from the GNU -Linker, CodeWarrior and RVCT
Microsoft Compiled HTML -Help
Microsoft PE COFF (Windows/MS-DOS -executables, object files, and import and static libraries)

Note that -comparisons of such files requires that Microsoft's DUMPBIN tool from Microsoft -Visual Studio v6 is installed.
Pre-processor (cpp.exe) -output
SGML (including XML -and HTML)
ZIP