OS/2 Professional/OS2PRO194.ISO/os2/com/utils/golded/bugfix/bdiff.doc

Text File | 1990-07-16 | 15.4 KB | 346 lines

BDIFF/BUPDATE: Binary file differencer/updater

What they do?
=============
  Bdiff creates a binary difference between two files. On unix like systems,
many people use diff and patch to update source files. They are very powerful
for "line oriented" data. However, they are incapable of handling binary data.
  Modifying a single line in source file amounts to a considerable difference
in its compiled object. Calling address, variable address, segment value, they
will all change even when object's structure remains similar.
  Bdiff creates the difference of two objects. Suppose, the difference will be
much smaller than whole new object file. With bupdate and "old object file",
you can create new object file from the difference file.

What's good?
============
  The merit of size, is very important if you distribute the difference on
line. And there is another reason to use difference. Only the person who
has "old version" can get new version of program. So, you can release the
update information of your charged program (commercial, shareware, etc.).
You do no need to bundle a document again. Cause, who use it, must have a
document bundled with the package of older version.
  Bdiff can pack many difference files into one file. You can see the
information of differences the file contents with bupdate command. With
composite difference file, you can update many files of a package at once.
Of course, not only program file, but document file can be updated with
BDIFF/BUPDATE. It is not so effective than to use diff/patch. Nevertheless,
it is much more convenient.
  Not only differences of different files, you can pack the differences for
same file, but between different versions.
  Suppose you released a program versions 1.1, 1.2, and 1.3. You can not guess
who holds which version. In such case, you can pack respective differences
between 1.1 and 1.2, between 1.2 and 1.3, and finally between 1.3 and the new
version 1.4.
  The holder of the program version 1.2, can update from his version to 1.3
then to 1.4. Bupdate checks the version and does this incremental updating
to the newest and will report its actions on the screen. You just watch it.
Difference data to incremental update, is more effective in the size than
the sum of all differences between new version and every respective version.


NOTE
====
  "CURRENT" outputs of Bdiff is not so compact. They must be larger than 1/8
of original program file size. You had better use compressing tools such as
LHarc to get down the size of up- downloading. In future version of Bdiff,
you may expect to have compressed output directly.
  If you use RCS for maintenance of source files, and write RCS header in
the program, you can let Bdiff automatically scan the header. Bdiff will
modify time stamps of files from the scan, and will record revision number
into difference file. This function of Bdiff makes maintenance of version
easier.
  If there is large difference between two files, Bdiff may fail to create
difference. The difference must be smaller than 16KB.
  Bdiff is effective enough for code changing, inserting, and deleting. But
it is not so for moving. Future version may be improved.


********** BDIFF

Usage:
======
  BDIFF [-swindow[:rate]] [(-r|-x)] [-i] [-a] [-v[rev:rev]] oldfile newfile [diffile]

  You have to assume two file names of old version file, and new version file.
You can not omit them. Of course, they are not the same name. To make
difference between two versions of a.exe, please rename older versions of a.exe
as a.old or such name. Otherwise, place them in different directories.
  You may not modify <newfile> name instead of <oldfile>. Because, This name
is recorded into differnce file, and used on updating.
Bdiff may cause some confusion when it meets a file with version number in
its name.
  The output has the name <diffile> if you specify it, otherwise the output
has the name combined with a prime name of <newfile> and default extension of
".bdf". You can omit <diffile> argument usually.

Suppose you create difference between bdiff123.exe and bdiff124.exe, you type:

    bdiff bdiff123.exe bdiff124.exe

to have the diffile bdiff124.bdf by default. The name implies that this
diffile is to update a program with name bdiff124.ext not bdiff123.ext.
The file bdiff123.bdf will try to update bdiff123.exe while bdiff124.bdf
searches for bdiff124.exe. You can not expect your user to have bdiff124.exe
since this is going to be the new version. If you type

    bdiff bdiff123.exe bdiff124.exe bdiff123.bdf
                                         ^^^^^^^
then you can get the BDF file with proper name. When you omit <diffile>
please be aware of the fact that <diffile> name is recorded in itself.

  There are some options. I will describe them below.

Options:
========
  -s:   To assume data span and required match rate in comparing. To assume
        span, use unit of byte. To assume ratio, use unit of per-cent.
        Default value of span is 15 bytes, and rate is 66%. It means if 10
        characters in each 15 succeeding characters of two compared files
        match, Bdiff believes two sets of data synchronize.
        If some data insertion/deletion occurs, data sync is broken. Then,
        Bdiff scans the context, and restart from a new position at which such
        sync is possible.
        Default values are reasonable to compare normal dos executable files.
        However, if you want to compare source/document files, you'd better
        assume large sapn/rate values. For example, -s20:100 option will give
        more effective outputs.
        If you do not specify rate you will have the default value of 80%.
  -r:   Good for source files. Output size remains the same if this option is
        on or off. Nevertheless, "compressed" file size may vary.
        I am not sure if this option may be valid in the future compatibility.
  -x:   Output "reverse" difference data with normal data. BDF files
        created with -x option, supports "version down" if need.
        Note that output contains a part of <oldfile>. Be careful about
        valid dates of copyright statement.
  -i:   Suppress time stamp comparison. Bupdate first check time stamp,
        sum, length of target to insure updating correct file. Of course,
        it is good way to compare time stamp. But if you loose released file,
        and time stamp is unknown (though contents of files are equal),
        use this option.
        RCS header will try to avoid such cases.
  -a:   Append difference data after existing BDF file. With this option,
        you can pack the difference of different files, between different
        versions.
  -v:   You can assume revisions of <oldfile> and <newfile> with this option.
        If you write RCS header in the objects, Bdiff records each version
        number in a difference file. If you don't, it is encouredged to assume
        each version number with this option.
        With -v option, Bdiff refrains from correcting time stamps even with
        RCS header. If you don't want to modify time stamp, use this option.

Return value
============
  0 for normal case, 1 for error.

Compatibility with older versions:
================================
  Omitted.
  PLEASE USE BDIFF1.2x OR LATER.

Examples:
=========
  Creating difference between Bdiff.old(1.1) and Bdiff.exe(1.2).
        bdiff bdiff.old bdiff.exe
  will create bdiff.bdf which is a difference between versions 1.1->1.2.

  Creating "reverse" difference.
        bdiff -x bdiff.old bdiff.exe

  Creating difference between non-RCS headered programs.
        bdiff -v1.1:1.2 bdiff.old bdiff.exe

  Add difference of document into created BDF file.
        bdiff -a -s20:100 bdoc.old bdiff.doc bdiff.bdf
  You do not need to specify Extension of "bdiff.bdf".


********* BUPDATE

Usage:
======
  BUPDATE (-v | -d | -x [-i[s]] [-r] [-o] [-wdir]) diffile [file[;source]..]

  Bupdate updates files using a deference file created by Bdiff. If more
than one difference is encountered in a single BDF file, Bupdate updates
all files required.
  It is also used to display the contents of BDF file, and to remove
some differences in a composite-difference BDF file.
  File names to update, are written in a BDF file. So most simple use,
only BDF file name is required for an argument, regardless of single difference
BDF or multiple differences BDF. To update bdiff.exe from 1.1 to 1.2,
type:

       bupdate bdiff.bdf
 or    bupdate bdiff

In normal usage, you actually not need to type filename extension ".bdf".
   After updating, extension of original files to update, will be modified
as ".org". If a file with an extension ".org" already exists, its extension
will be renamed as ".nnn" where nnn is a 3 digit number.
  You can also give file name templates after BDF file name. They can
include wildcards in themselves. If they assumed, bupdate procceeds execution
for only files whose name match to the templates. To update exe files only, use
"*.exe" as a template.
Type:

       bupdate bdiff *.exe

when you have files bdiff.exe and bdiff.doc in the curent directory.
  You can add a "path" for the templates. This is useful in updating files
in some other directory. In case when files to be updated are in drive C:,
type:
        bupdate foo.bdf c:*.*

  Updating files must have exactly the same contents to the ones used to
create differences. Bupdate checks time stamps, sums, lengths. For some
reason, if you want time stamp comparison to be ignored, use -i option which
is described below. If -i option was assumed on creating difference, time
comparison is always ignored.

Options:
========
  -v:   Verbosely outputs contents of BDF file. Prints file names to update,
        time stamps of old and new versions of the file, their file size,
        their revisions, and BDF file size.
        This option is useful to see what version is required to update.

  -d:   Deletes differences whose name match to file name templates given.
        Original BDF file is renamed as ".bak", and saved.

  -x:   Updates files. Without -v and -d options, this option assumed as a
        default.

  -i:   Ignores time stamps. If you modified time stamps of updating files
        for some reason(ex. re-compiling), this option will help you.

  -is:  Ignores time stamps and sums. This option is useful to update "patched"
        versions of files.
        Assuming you have a1.exe, and a1a.exe watch is patched version of
        a1.exe. When a2.exe, which is a new version of a1.exe, released,
        first creates difference between a1.exe and a2.exe. Then assume it
        to a1a.exe with -is option. You may get a good version of a2a.exe
        under favorable circumustances.

  -r:   Updates in reverse order. It means "version down". Create <oldfile>
        from <newfile> for bdiff. Of course, BDF file must be created with
        -x option.

  -o:   Omitting backups. As described above, original files are renamed and
        preserved. This is to save disk space when you try incremental
        updates. With this option, all original files are discarded.
        RESERVE ORIGINAL FILES BEFORE UPDATING WITH -o OPTION, OR APPLY TO
        COPIED FILES ONLY.

  -w:   Specify Working directory.

Return value:
=============
0 for success updating all files, 1 for error updating at least one file.


Compatibility to older versions:
================================
OMITTED. USE BUPDATE1.2x OR LATER.


Source file assuming:
====================
  As explained above, <newfile> name is used as a updating file name. If it has
version numbers in it, the kind of trouble you may expect is as follows.
Suppose program distributer is going to update BDIFF123 to BDIFF124.
distributer types:

    bdiff bdiff123.exe bdiff124.exe

and bdiff124.bdf will be created. What happens then? You as a user have the
difference bdiff124.bdf and bdiff123.exe. While, Bupdate looks for
bdiff124.exe to update. You have to copy bdiff123.exe into bdiff124.exe
or rename so before updating. Sounds complicated.
  In such case, source file assuming will do. You can give a source file name
just after filename templates separated by a semi-colon. Templates are exact
source file names, should not have wildcards. In case above, you type:

        bupdate bdiff124.bdf bdiff124.exe;bdiff123.exe

to avoid copying. If bdiff124.bdf encounters only one difference, you can
type in short:

        bupdate bdiff124 ;bdiff123.exe

  After all, I dare to say including a version number in a file name is not
a good manner. Use time stamp instead.


************ modtime

Usage:
  modtime filename

  This program is used to set time stamp according to RCS header included.
Modify time stamp before INITIAL release. It will make you free from
remembering time stamp of released one.



************ bupmini

Usage:
  bupmini bdf_file

  This tiny program is for update only. This program does not have the
ability to display or modify the contents of BDF file.
This program acts just as bupdate with -o option, does NOT create backups.
You have to preserve origainal files for your own sake.
  Slightly modified version of bupmini, makes "self updating" BDF file enable.
Please contact us for such version.

+-------------------------------------------------------+
|This file is not contained in English Version of Bdiff.|
+-------------------------------------------------------+

************ COPYRIGHT and OTHERS

  Term of "this program" described below, means all programs and documents
contained in this archive. And what described below, are affected to this
version only. They may be changed without notice in future.

On distributing and using:
==========================
* All copyrights of this program are reserved by the author.
* You can distribute this program freely if
  - distributing this program only (not with other programs)
  - not changed
  - free without media charge
  - not any copyrights restricted by distributing (it means, for example,
    never upload on a BBS who claims copyrights of uploaded programs).
* You can use this program to create difference free, and release difference
  data created by this program free, regardless of commercial or no-commercial
  base.
* Please contact us to use this program itself (ex. adding  update program
  with difference, and distributing it).
* NO WARRANTY OF THIS PROGRAM. THIS PROGRAM IS SUPPLIED AS-IS.
  WE ASSUME NO LIABILITY FOR DAMAGES DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT
  FROM THE USE OF THIS PROGRAM.



                                                       Toshiyuki TANAKA
                                                       TNT Technology corp.

                                                       KAKINOKIZAKA 3-6-7-111,
                                                       MEGURO, TOKYO
                                                       152 JAPAN

                                                       [phone] may accept
                                                       your "AUTO DIALED" fax.

                                                       Oversea Users Contact
                                                       K.Okubo Genie,
                                                       74100,2565 Compuserve,
                                                       or E-Mail address:
                                                       [e-mail]