@DATABASE GPatch.guide
@MASTER GPatch.guide
@$VER: 2.1
@AUTHOR "Ralf Gruner"
@(c) "© 1997 Ralf Gruner, Großschönau, Germany"
@INDEX "Index"

@NODE "Main" "GPatch Manual"
@{JRIGHT}***RGR***
@{JCENTER}
@{b}@{u}GCompare / GPatch:@{ub}  The patch system for program updates@{uu}

Version 2.1

Author: Ralf Gruner


@{JLEFT}
@{LINDENT 3}

@{" Introduction " LINK "Introduction" 0}
@{" GCompare " LINK "GCompare" 0}
@{" GPatch " LINK "GPatch" 0}
@{" Hints " LINK "Hints" 0}
@{" Technical Details " LINK "Details" 0}
@{" Example " LINK "Example" 0}
@{" Copyright, Distribution, Disclaimer " LINK "Copyright" 0}
@{" History " LINK "History" 0}



@ENDNODE

@NODE "Introduction" "Introduction"
@SMARTWRAP
@{LINDENT 1}

@{B}Introduction@{UB}


GCompare generates patch files for the distribution of updates for any files.


GPatch applies these patches.



The features of GCompare/GPatch are:

@{LINDENT 2} @{PARI -1}

-The patch file can contain patches for any number of files.
So you can distribute the update for a lot of versions in one file.
If the directory structure of your product is unchanged, then the patcher
will find the required patches without any additional actions of your update
script.
And you can put the patches for different files of your product in one
patch file.


-If the patchfile contains the changes from each version of your program to
the next then it is not necessary to store all old versions.


-The format of the patchfile is very high optimized.
GCompare tries some different coding algorithms and selects that with the
shortest result.
I do not know too many similar programs, but I think in the most cases
GCompare produces the shortest patch files of all available patch programs.


-To avoid corrupt files, the programs contain a very safe error checking
(CRC32 signatures for all files). So you can be sure that the result of the
patch process is perfect if no error messages appear.



@ENDNODE



@NODE "GCompare" "GCompare"
@SMARTWRAP
@{LINDENT 1}

@{B}GCompare@{UB}


GCompare is a shell command.


Format:


@{LINDENT 3}

 GCompare <old file> <new file> <patch file> [mode <n> | quick]

@{LINDENT 1}


GCompare compares the old file with the new file and saves all changes in
the patch file.

If GCompare finds an existing patch file, then it appends the patches.

If a patch file already exists, then GCompare searches for matching data
in this file too.

Later GPatch can build the new file using old file and the patch file.


In case of errors GCompare displays an error message.

Any fatal error produces a return code of 15, and if the result is a corrupt
patch file then it will be deleted.


You can use the options "mode" and "quick" to select an operating mode:
Without these options GCompare selects the optimal type.
With the option "mode" you can select it and "quick" is a fast mode for very
large files.
The mode values <n> can be the numbers 1 to 4.


GCompare needs enough free memory for old file, new file and the patch file.
If GCompare can not allocate enough memory for the list search algorithm
(altogether 9 times the filesize of the old file plus 2 KB), then it uses
the mode 3 (needs only linear search).


For the search in the already existing patch file it is the same.
If there is not enough memory (9 times the filesize of the patch file plus
2 KB) then GCompare searches only in the old file.


@ENDNODE


@NODE "GPatch" "GPatch"
@SMARTWRAP
@{LINDENT 1}

@{B}GPatch@{UB}


GPatch is a shell command.


Format:


@{LINDENT 3}

GPatch <old file> <patch file> <new file> [recursive]

@{LINDENT 1}


GPatch creates the new file using the old file and the patch file.

It selects the matching patches by file size and CRC signature.


In case of errors GPatch displays an error message.

Any fatal error produces a return code of 15, and if the result is a corrupt
new file then it will be deleted.


The argument "recursive" selects the recursive operating mode. In this mode
GPatch tries again to patch after each successful patch until no matching
patches are found, using the new file as old file.

You can use this operating mode if you do not want to store all your old
program versions.

The patch file should then not contain the changes of all old versions
to the newest version, but the changes from each version to the next.


@ENDNODE


@NODE "Hints" "Hints"
@SMARTWRAP
@{LINDENT 1}

@{B}Discussion and hints@{UB}


I have got some mail about the speed and the size of the resulting patch
file.
Some of you found the patch file size much shorter than of other patchers,
some of you not, and all want a faster compare program.


Because it is impossible to develop a format of the patch file with always
the shortest result (because the file size depends on the distance of the
matching data and the way to address it) GCompare has four algorithms.
The optimizer selects the best format, but this takes four times of computing
time.
If you want not wait for the optimizer then you can select the file format
with the "mode" argument.
In the most cases "mode 1" provides a good result. If for very large files
GCompare needs too much time then you can use "mode 3". The argument "quick"
is for the fastest search, but then the patch file will be larger.


If you compare the results of GCompare with the results of other programs,
you should do this with compressed versions of the patch files too. GCompare
has no built in compression (different from other compare programs with run
length encoding), because I think all distribution files will always be
compressed before they are published and double compressing will decrease
the effectivity.


GCompare searches matching data in the patch file too if it already exists.
The more patches of different versions of the same program the patch file
contains, the more effective the resulting patch file will be, compared with
single patch files.



Speed: There is really no chance to make GCompare much faster. GCompare
searches matching data in the entire old file (and not only in a relative
area like other compare programs). If you have not enough time, I suggest you
to use the quick mode.



GPatch can not handle the old GCompare file formats (I want a small patch
program). If you need an older version then use version 1.4 or 1.6.

If GPatch detects an old patch file then it tells you which version you need.


@ENDNODE

@NODE "Details" "Technical Details"
@SMARTWRAP
@{LINDENT 1}

@{B}Technical Details@{UB}


@{B}mode 1@{UB}


Mode 1 is the most effective if the most changes are shorter than 128 bytes.


@{B}mode 2@{UB}


Mode 2 is the most effective for many very small changes.


@{B}mode 3@{UB}


Mode 3 finds matching data only in a relative area of 64 KB.

It needs only linear search and is practical for very large files.


@{B}mode 4@{UB}


Mode 4 is similar mode 1, but better if you have fewer but larger changes.


@{B}quick@{UB}


The quick mode produces the same file format as mode 3, but it searches only
in a relative area of 256 bytes for matching data.


@ENDNODE

@NODE "Example" "Example"
@SMARTWRAP
@{LINDENT 1}

@{B}Example@{UB}



As GCompare example I have included scripts for a fictive program.


@{" MakePatchFile " LINK "ExampleScripts/MakePatchFile/MAIN"} creates
the patch file
and @{" UpdateMyProgram " LINK "ExampleScripts/UpdateMyProgram/MAIN"} applies
the patches.


The old versions of the example program "MyProgram" are in "Archive". The
patches for the program and a manual "MyProgram.readme" will be applied on the
distribution disk "MyProgram".


@ENDNODE

@NODE "Copyright" "Copyright, Distribution, Disclaimer"
@SMARTWRAP
@{LINDENT 1}

@{B}Copyright@{UB}


GCompare and GPatch are Copyright © 1997


Ralf Gruner, An der Sense 5a, D-02779 Großschönau, Germany

ralf.gruner@t-online.de



@{B}Distribution@{UB}


GCompare and GPatch are freeware programs. You can use it for all your needs
without restrictions. Also use for commercial products is free.


If you want to see future updates of the programs, please send me an email
that you use the programs. There are some things to improve yet, but if nobody
need it I can do other things.

Any comments are welcome.



@{B}Disclaimer@{UB}


THIS PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY
OF FITNESS FOR A PARTICULAR PURPOSE.  THOUGH EVERY CARE HAS BEEN TAKEN TO
MAKE THIS PROGRAM SYSTEM-FRIENDLY AND BUGS-FREE, THE ENTIRE RISK AS TO THE
RESULTS, RELIABILITY AND PERFORMANCE OF THIS PROGRAM IS ASSUMED BY YOU.


@ENDNODE

@NODE "Credits" "Credits"
@{LINDENT 1}
@SMARTWRAP

@{B}Credits@{UB}


@{" I " LINK "Copyright" 0} have to thank for sending me emails:


Thomas Baust

Christian Beck

Domenic Gebauer

John Girvin

Bernardo Innocenti

Richard Koerber

Tom Newton

Maik Schreiber

Dirk Stöcker.


@ENDNODE

@NODE "Index" "Index"
@{LINDENT 1}

@{B}Index@{UB}
@SMARTWRAP


C

@{" Copyright " LINK "Copyright" 0}


E

@{" Example " LINK "Example" 0}


G

@{" GCompare " LINK "GCompare" 0}

@{" GPatch " LINK "GPatch" 0}


H

@{" Hints " LINK "Hints" 0}

@{" History " LINK "History" 0}


M

@{" mode " LINK "Details" 0}




@ENDNODE


@NODE "History" "History"
@{LINDENT 1}
@{B}History@{UB}

19.04.97: GCompare 1.0 / GPatch 1.0
Inital release.

21.04.97: GCompare 1.1 / GPatch 1.1
Bugfix. Better examples.

26.04.97: GCompare 1.2 / GPatch 1.2
Speed improvements.

01.05.97: GCompare 1.3 / GPatch 1.3
Bugfix (GPatch failed on the most files greater than 64KB).

11.05.97: GCompare 1.4 / GPatch 1.4
GCompare uses a faster search algorithm.

01.06.97: GCompare 1.5 / GPatch 1.5
New file format (shorter patch files).
Some small changes.

05.07.97: GCompare 1.6 / GPatch 1.6
Bugfix: Possible counter overflow with large data blocks.

23.11.97: GCompare 2.0 / GPatch 2.0
File size limit increased (from 8MB to 2GB).
GCompare searches matching data in the already existing patch file too.
Three new coding algorithms.
GCompare uses an optimizer for best results.
Compiled with SAS/C 6.58 now - 20% shorter and 5% faster.

04.12.97: GCompare 2.1 / GPatch 2.1
Recursive mode for GPatch implemented.
Better reaction in case of syntax errors or bad files.

@ENDNODE