diff --git a/Contrib/VPatch/Readme.html b/Contrib/VPatch/Readme.html index d977479f..62e63e31 100644 --- a/Contrib/VPatch/Readme.html +++ b/Contrib/VPatch/Readme.html @@ -1,341 +1,341 @@ - - - -VPatch 3 - - - - - - - + +
- + + + +VPatch 3 + + + + + + + - -
+

VPatch 3.1

-
-

Introduction

-
-

VPatch allows to create a patch file to update previous versions +

+

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
    • -
+ 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, in the patch file, + 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 codeDescription
0Success
1Arguments missing
2Other error
3Source 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

-
+ 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 codeDescription
0Success
1Arguments missing
2Other error
3Source 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 +

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.

-
-

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.

-
-
-

Version history

-
-
    -
  • 3.1 -
      -
    • GenPat now compiles on POSIX platforms (MinGW/GCC), Visual - C++ 6 and Borland C++.
      • -
    • More test cases to verify functionality of GenPat.
      • -
    -
    • -
  • 3.0 -
      -
    • Final: Updates to the GUI, installer
      • -
    • 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.
      • -
    • 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).
      • -
    • 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.
      • -
    • 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.
      • -
    • Target file date is now preserved inside a patch and restored - on the user system.
      • -
    • MD5 checksums are now used instead of CRC32 checksums, unless - existing patches in a file already are in CRC32 mode.
      • -
    • 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.
      • -
    • 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.
      • -
    • 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.
      • -
    • 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 -
      -
    • 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.
      • -
    • 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 -
      -
    • 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 -
      -
    • All new algorithm used in the patch generator: much faster - (up to 90%) while using smaller block sizes (higher compression)
      • -
    • Created a NSIS 2 plugin
      • -
    • Works with small files
      • -
    • 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

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

+
+
+

Version history

+
+
    +
  • 3.1 +
      +
    • GenPat now compiles on POSIX platforms (MinGW/GCC), Visual + C++ 6 and Borland C++.
      • +
    • More test cases to verify functionality of GenPat.
      • +
    +
    • +
  • 3.0 +
      +
    • Final: Updates to the GUI, installer
      • +
    • 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.
      • +
    • 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).
      • +
    • 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.
      • +
    • 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.
      • +
    • Target file date is now preserved inside a patch and restored + on the user system.
      • +
    • MD5 checksums are now used instead of CRC32 checksums, unless + existing patches in a file already are in CRC32 mode.
      • +
    • 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.
      • +
    • 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.
      • +
    • 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.
      • +
    • 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 +
      +
    • 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.
      • +
    • 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 +
      +
    • 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 +
      +
    • All new algorithm used in the patch generator: much faster + (up to 90%) while using smaller block sizes (higher compression)
      • +
    • Created a NSIS 2 plugin
      • +
    • Works with small files
      • +
    • 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.
-
-
-
-
- - + +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. + + + +
+ +