evalid command syntax

evalid compares two files, or two trees of files, ignoring non-significant differences in some types of files. You can use it to check that the behaviour and compatibility of a build has not changed, without needing to run more complex BC checking tools or regression tests.

A typical situation when evalid is useful is when you make a change in the source code or in the build environment that you believe should not affect the content of the built files. Such source changes could include adding comments, or adding configured code that should not be built in the configuration that you are testing. You can use evalid to compare the new build against a previous build, and discover if there are in fact any differences between the builds.

A standard diff tool is not adequate for this task, as build output files typically contain some environment information, such as time stamps, which diff would flag as differences. evalid recognizes the common types of file in a build, and follows comparison rules that allows it to ignore such non-significant 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 a Symbian OS kit. You can invoke it with a number of different options, according to the task you want to perform. This section describes these options.

The results from 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 later 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 further options:

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 files 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 should 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 files by comparing 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.

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

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

For a direct comparision, the meaning of these messages is as follows:

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

These are the types of file for which evalid has special support for finding and ignoring non-significant 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