|
||
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:
|
Exclude files with names that match the specified Perl regular expression. Syntax for Perl regular expressions can be found at http://www.perl.com. |
|
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:
|
Provide verbose information about failed comparisons. This has no effect on MD5 operations. |
|
Print results to standard out (i.e. the screen). |
|
Append results to specified file.
This has no effect when used with |
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 |
|
Files are exactly the same. For example:
|
|
The files are different, but the comparison rules for the file type indicate that the difference is not significant. For example:
|
|
A file that is present in the first tree is not present in the second. For example:
Note that |
|
There is a significant difference between the files. If
For example:
|
For an MD5 comparison, the meaning of these messages is as follows:
Message type |
Explanation |
|
Files have no significant differences. |
|
There is a significant difference between the files. |
|
A file listed in the first MD5 file is not present in the second. |
|
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