VPatch - Free Patch Generator

Homepage: http://www.tibed.net/vpatch/

VPatch is a Freeware/OpenSource application that allows you to create a patch file to update previous versions of a given file.

current version: 3.2 (January 2008)

**********************************
VPatch 3.2

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\GenPat32\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.

Test framework (Python)

Run the VPatch_tests.py script (if you have Python installed) to perform basic functionality tests on VPatch. The testExtended test is known to fail if a set of big test files is not installed, you can safely ignore this.

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-2008 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.

and now some insight:

Using the interface

Step 1. Start the interface (VPatchGUI.exe).
Step 2. Hit the "Add new version" button. Now, select the latest version of your file. Right after that, another file selection screen pops up. Now, select all older versions of your file (which need to be updated).
Step 3. You're set, you can add more files if you want through the "Add new version" button.
Step 4. Configuration: By default a "Block size" of 64 is configured. If you make it smaller, you will get smaller patch files. You can set this to 16 to squeeze out even that last byte, but applying the patch file can get slower when using such small block sizes. Also, memory usage during patch generation will be higher.
Step 5. Hit "Generate patches" from the Action menu. Your patches are now being generated.
Step 6. If you select "Create patch file" now, the program will create an PAT which contains the information needed to update all old files to new versions. This PAT file can be used to update files. If you want to do this with NSIS, see the other readme file. If you want to use it standalone, you should create an EXE file instead of a PAT file. However, the recommended way to use patches with NSIS now uses plugins, see the other readme for info about that.

• The 'Create PAT' option is for creating a patch for use with NSIS 2
• The 'Create EXE' option is for creating a patch attached to a stand-alone EXE. Read below for steps on how to use this command-line patch.
• The 'Create DLL' option is for creating a patch attached to a stand-alone DLL (useful for Inno Setup)

Using command-line utilities

Step 1: Creating the patch file(s)

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

GENPAT (sourcefile) (targetfile) (patchfile)

In my example, I use the following call:

GENPAT data.dta data_20.dta data.pat

Now, the patch will be generated. This will take some time. You can repeat
this step for multiple different files:

GENPAT title.pcx title2.pcx data.pat

Note: GenPat returns an error code if something went wrong as of v2.1. Please see the other readme for a description of these error codes.

Step 2: Piecing things together

The patch files created in step 1 should now be attached to the VPatch runtime. Or read the alternative step 2 below. Once attached, you can run this file on the target system and it will update the files. In order to piece the patch files together, use VAppend.exe:

VAPPEND (patchfile) [output file] [runtime]

This will create a file called VPatch.exe by default, which is the actual patch. The default runtime is VPatch.bin. In my example:

VAPPEND data.pat

So this is the same call as:

VAPPEND data.pat vpatch.exe vpatch.bin

Note that "vpatch.bin" corresponds to "Create EXE" in the GUI and that "vpatchdll.bin" corresponds to "Create DLL" in the GUI. The stand-alone patch (which is not attached to a runtime) is the one you get if you use "Create PAT" in the GUI.

Step 3: How to use it (the command-line EXE version)

If you want to use your patch in NSIS, please read the other readme. This description is about the stand-alone EXE version.
Now that the patch is ready, you (could) use it. You can call VPatch.exe in the following way:

VPATCH.EXE (sourcefile) (outputfile)

IMPORTANT: You must specify the full filename of VPatch, so VPatch.exe. If you call it using just "VPatch" then you will get an error.
In the example this would be:

VPATCH.EXE data.dta data.new

This way, VPatch will use data.dta and patch it. It will create data.new, which contains the new version. The original data.dta isn't touched. If the file data.new isn't created, an error must have occured.
If you have multiple files attached, you can make multiple calls to VPatch. The program will automatically choose the correct patch for the file:

VPATCH.EXE data.dta data.new
VPATCH.EXE title.pcx title.out

Step 2 (alternative): stand-alone runtime and patch

If you do not want to attach your patch file to a runtime, you can also use it in a more stand-alone manner using the VPatchPrompt.exe runtime. This runtime will first check if it has a patch attached and, if it does not, it will take the patch file as the first command-line argument:

VPATCHPROMPT.EXE (patchfile) (sourcefile) (outputfile)

Another feature of this runtime is that it will prompt the user for a filename, if a command-line argument is not specified. Therefore, if you call VPatchPrompt without arguments, you will be prompted for all three command-line options (or, if you have attached a patch to the VPatchPrompt runtime using VAppend, it will only prompt for the source and output files).