evalid Command Syntax

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.

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

> evalid [log-options] file1 file2

This compares file1 against file2.

> evalid [log-options] directory1 directory2

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

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

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

> evalid [log-options] -m file1 file2

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

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

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.

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.

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.

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.

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

• ELF format

• E32 Image (Symbian OS 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