Wtyczka VPatch 3.1

Ten dokument zgodny jest z NSIS 3.1


1. Wprowadzenie

VPatch pozwala na utworzenie pliku aktualizującego (łatki), który umożliwia uaktualnienie starszej wersji twojego oprogramowania do nowszej. Narzędzie GenPat tworzy plik aktualizacyjny. Wtyczka może użyć ten plik aktualizujący do zaktualizowania pliku. Dzięki użyciu pliku aktualizującego, możesz znacznie zredukować rozmiar aktualizacji do pobrania, ponieważ w pliku tym zapisane są tylko informacje o różnicach pomiędzy plikami.

2. Sposób użycia


2.1 Utworzenie pliku aktualizującego


Upewnij się, że masz plik źródłowy (wersja oryginalna) oraz plik docelowy (wersja do zaktualizowania). Na przyklad, DATA.DTA (znajdujący się w systemie użytkownika) oraz DATA_20.DTA (wersja 2.0 tego pliku z danymi). Teraz, wywołaj narzędzie GenPat.exe, korzystając z linii poleceń:

GENPAT oldfile.txt newfile.txt patch.pat

Utworzony zostanie plik aktualizujący, zajmie to parę chwil.

Używając parametru /B=(Rozmiar Bloku (BlockSize)) narzędzia GenPat (wstaw po nazwie pliku), możesz użyć różnego rozmiaru bloku. Mniejszy rozmiar bloku może przyczynić się do utworzenia plików aktualizujacych o mniejszym rozmiarze, lecz ich tworzenie może potrwać nieco dłużej (domyślny rozmiar bloku równy jest 64).

Jeśli masz problemy z użyciem tego narzędzia, które pracuje w linii poleceń, możesz pobrać GUI (graficzny interfejs użytkownika) dla VPatch z poniższej strony: http://www.tibed.net/vpatch.


2.2 Aktualizacja pliku podczas instalacji


Użyj wtyczki VPatch, aby zaktualizować plik używając pliku aktualizującego:

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

Wynik operacji aktualizacji zostanie dodany na stos i może przyjąć jedną z poniższych wartości (w nawiasie podano polski przekład):

  • OK
  • OK, new version already installed (OK, nowa wersja pliku jest już zainstalowana)
  • An error occurred while patching (Wystąpił błąd podczas aktualizowania pliku)
  • Patch data is invalid or corrupt (Dane aktualizatora są nieprawidłowe lub uszkodzone)
  • No suitable patches were found (Nie znaleziono odpowiedniego pliku do zaktualizowania)

Przykład możesz znaleźć w pliku example.nsi (Examples/VPatch/example.nsi). Powinieneś sprawdzać czy łańcuch znaków na stosie zaczyna się od słowa OK, ponieważ oznacza to, że proces aktualizacji zakończył się powodzeniem i możesz zmienić nazwę plikowi temporary_newfile.txt w nazwę oldfile.txt by zastąpić plik oryginalny, jeśli chcesz.


2.3 Wielokrotna aktualizacja w jednym pliku


GenPat dołącza dane aktualizatora do pliku, który wcześniej określisz. Jeśli istnieje już plik aktualizacyjny dla tego samego oryginalnego pliku, z tą samą sumą CRC, w pliku aktualizatora, plik aktualizacyjny zostanie zastąpiony. Na przykład, jeśli chcesz mieć możliwość aktualizacji wersji 1 oraz 2 do wersji 3, możesz wstawić dane aktualizacyjne pliku 1 > 3 oraz 2 > 3 do tego samego pliku.

Możesz również wstawić dane aktualizacyjne dla różnych plików w jednym pliku aktualizacyjnym, na przykład, dane aktualizacyje z pliku A w wersji 1 do pliku A w wersji 2 oraz dane aktualizacyjne z pliku B w wersji 1 do pliku B w wersji 2. Po prostu wywołaj wtyczkę wielokrotnie, z podanym tym samym plikiem aktaulizacyjnym. Prawidłowe dane aktualizacyjne zostaną automatycznie wybrane (dzięki danym CRC).


2.4 Kody wyjścia generatora plików aktualizacyjnych (GenPat)


W wersji 3 dostępne są następujące kody wyjścia (znane też jako poziomy błędu, w czasach DOS), zwracane przez GenPat. GenPat zwróci kod wyjścia zależny od przebiegu procesu generowania pliku aktualizacyjnego. Poniżej znajduje się lista możliwych kodów wyjścia:

  • 0 = Sukces
  • 1 = Brak podanego parametru
  • 2 = Inny błąd
  • 3 = Plik źródłowy posiada już dane aktualizacyjne w określonym pliku (ERROR), użyj przełącznika /R, aby je nadpisać

Wymienione powyżej kody wyjścia mogą być użyteczne przy tworzeniu plików aktualizacyjnych poprzez skrypty NSIS.

3. Kod źródłowy

Kod źródłowy dostępny jest w oryginalnym pakiecie oraz w repozytorium SVN pakietu NSIS.


3.1 Wtyczka NSIS (C++)


Kody źródłowe wtyczki NSIS można znaleźć w katalogu Source\Plugin.


3.2 Generator plików aktualizacyjnych (C++)


Najciekawszy element VPatch, bieżący algorytm generowania plików aktualizacyjnych, można znaleźć w pliku Source\GenPat\PatchGenerator.cpp. Plik nagłówkowy tego pliku zawiera krótkie wyjaśnienie zasady działania algorytmu.


3.3 Interfejs użytkownika (Delphi)


Interfejs użytkownika jest także załączony, ale plik wykonawczy GUI musisz utworzyć sam, ponieważ jest zbyt duży by go dołączyć do dystrybucji. Poza środowiskiem Borland Delphi 6 lub nowszym (możesz użyć jego darmowej wersji Personal), będziesz musiał także zainstalować komponent VirtualTreeView napisany przez Mike'a Lischke.

4. Autorzy

Napisał: Koen van de Sande

Wtyczka w języku C napisana przez Edgewize, zaktualizowana przez Koen van de Sande

Nową dokumentację oraz przykład napisali Joost Verburg oraz Koen van de Sande

5. Licencja

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.