--- a/Symbian3/PDK/Source/GUID-35DF14C7-62B6-51C0-8F4C-EF1B4A1173DD.dita Fri Jul 02 12:51:36 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,223 +0,0 @@
-<?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_<file1>_to_<file2>.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_<file1>_to_<file2>.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 <logfile></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: ... (<type>)</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>
-</conbody></concept>
\ No newline at end of file