

VPatch 3.1


Introduction

VPatch allows to create a patch file to update previous versions of your
software. The GenPat utility generates the patch file. The plug-in can use the
patch to update a file. Using a patch, you can reduce the download size of your
updates because only the differences between the files are included in the
patch file.

How to use


Generate the patch file

Make sure you have the source file (original version) and the target file
(version to update to). For example, DATA.DTA (currently on user system) and
DATA_20.DTA (version 2.0 of this data file). Now call the command line tool
GenPat.exe:

  GENPAT oldfile.txt newfile.txt patch.pat

Now, the patch will be generated, this will take some time.
Using the /B=(BlockSize) parameter of the GenPat utility (put it after the
filenames), you can use a different block size. A smaller block size may result
in a smaller patch, but the generation will take more time (the default
blocksize is 64).
If you have trouble using this command-line utility, you can download a GUI
(graphical user interface) for VPatch from its own website: http://
www.tibed.net/vpatch.

Update the file during installation

Use the VPatch plug-in to update a file using a patch file:

  vpatch::vpatchfile "patch.pat" "oldfile.txt" "temporary_newfile.txt"

The result of the patch operating will be added to the stack and can be one of
the following texts:

* OK
* OK, new version already installed
* An error occurred while patching
* Patch data is invalid or corrupt
* No suitable patches were found

Check example.nsi for an example. You should check whether the stack string
starts with "OK" because then the patch has succeeded and you can rename
"temporary_newfile.txt" to "oldfile.txt" to replace the original, if you want.

Multiple patches in one file

GenPat appends a patch to the file you specified. If there is already a patch
for the same original file, with the same CRC/MD5, in the patch file, the patch
will be replaced. For example, if you want to be able to upgrade version 1 and
2 to version 3, you can put a 1 > 3 and 2 > 3 patch in one file.
You can also put patches for different files in one patch file, for example, a
patch from file A version 1 to file A version 2 and a patch from file B version
1 to file B version 2. Just call the plug-in multiple times with the same patch
file. It will automatically select the right patch (based on the file CRC).

Patch generator (GenPat) exit codes

In version 3 the following exit codes (known as error levels in the DOS period)
can be returned by GenPat. GenPat will return an exit code based on success of
the patch generation. Here is a list of the possible exit codes:

Exit code Description
0         Success
1         Arguments missing
2         Other error
3         Source file already has a patch in specified patch file (ERROR), use
          /R switch to override

These exit codes can be useful when you generate patch files through a NSIS
script.

Source code

Source code is available in the original package and in the SVN repository of
NSIS.

NSIS plug-in (C++)

The source of the NSIS plug-in that applies patches can be found in the
Source\Plugin folder.

Patch Generator (C++)

The most interesting part of VPatch, the actual patch generation algorithm, can
be found in Source\GenPat\PatchGenerator.cpp. The header of that file contains
a brief explanation of the algorithm as well.

User interface (Delphi)

A user interface is included as well, which you will have to build yourself
because the GUI executable was too large to include. Besides Borland Delphi 6
or higher (you can use the freely available Personal edition), you will also
need to install the VirtualTreeView component by Mike Lischke.

Version history


* 3.1

  o GenPat now compiles on POSIX platforms (MinGW/GCC), Visual C++ 6 and
    Borland C++.
  o More test cases to verify functionality of GenPat.

* 3.0

  o Final: Updates to the GUI, installer
  o RC8: GenPat will now flag replacement of a patch (e.g. the source file has
    the same contents as a previous patch inside a patch file) as an error. You
    can specifically allow it using the /R switch. Added license to source
    files.
  o RC7: Fixed critical bug in GenPat with multiple patches in a single file.
    Fixed serious bug in stand-alone EXE runtime: process kept on running
    forever. Included case testing through a Python script to test common usage
    (and prevent bugs like the one in GenPat in the future).
  o RC6: Upgraded to non-beta compiler. Added /A switch to change block match
    limit and /O to deactivate the limit. Updated GUI to support the /O switch.
  o RC4a to RC5a: input block size is now checked for power of 2 and fixed if
    incorrect. When patch file does not yet exist, no longer forgets to create
    the header. No longer tries to allocate memory when there are no chunks.
    Fixed memory leaks.
  o Target file date is now preserved inside a patch and restored on the user
    system.
  o MD5 checksums are now used instead of CRC32 checksums, unless existing
    patches in a file already are in CRC32 mode.
  o The patch generator, GenPat, has been completely rewritten in C++. It no
    longer needs to keep the entire files in memory, instead memory usage is a
    certain percentage of the source file size. The percentage is based on the
    block size, larger block sizes will reduce memory usage.
  o All runtimes now share a common codebase, perform proper error checking and
    don't leave behind files if the input file was already up to date.
  o Bug Fix: The patch generator algorithm no longer reduces to a quadratic
    runtime if there are many blocks with the same content in the files to
    patch.
  o Bug Fix: The documentation of the command-line utilities was incorrect and
    no warnings would be given by the runtimes, causing the patch not to work
    (this does not apply to NSIS patches).

* 2.1

  o Added argument checking and error handling to GenPat. Now returns exit
    codes as well to indicate success/failure (and the reason for failure).
    Only GenPat has changed in this version compared to 2.0 final.
  o Bug Fix: GenPat no longer gives an Access Violation when attempting to
    patch a file smaller than 64 bytes into a file larger than 64 bytes.

* 2.0 final

  o Cleaned up source code for the patch generator, which is now included (this
    code is written in Borland Delphi 6 and compiles with the freely available
    Personal edition).

* 2.0 beta 2

  o All new algorithm used in the patch generator: much faster (up to 90%)
    while using smaller block sizes (higher compression)
  o Created a NSIS 2 plugin
  o Works with small files
  o Replaces existing patch in file if original file CRC is identical



Credits

Written by Koen van de Sande.
C plug-in initially by Edgewize, updated by Koen van de Sande.
New documentation and example by Joost Verburg and Koen van de Sande.

License


  Copyright (C) 2001-2005 Koen van de Sande / Van de Sande Productions

  This software is provided 'as-is', without any express or implied
  warranty. In no event will the authors be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute
  it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented;
     you must not claim that you wrote the original software.
     If you use this software in a product, an acknowledgment in the
     product documentation would be appreciated but is not required.
  2. Altered versions must be plainly marked as such,
     and must not be misrepresented as being the original software.
  3. This notice may not be removed or altered from any distribution.

