VersionCopy
===========

VersionCopy ist ein Programm, mit dem die versionierte Verteilung von Softwarepaketen
vorgenommen werden kann. Die Funktionen im berblick:

- Anhngen von Versionsinformationen an den Namen der Installationsdatei
- Erzeugen einer Datei mit Versionsinformationen fr die Downloadseite
- Erzeugen einer MD5-Checksumme
- Kopieren aller zum Projekt gehrenden Dateien in beliebige Windows-Verzeichnisse
  oder per FTP auf einen oder mehrere Downloadserver
- Automatische Anpassung von HTML-Seiten (Version, Datum, Gre, MD5)

Zur Automatisierung mit Batch-Dateien ist eine Steuerung ber die Befehlszeile
mglich.

Voraussetzungen:
----------------
1. Eine ausfhrbare Datei mit den Versionsinformationen des Projekts (z.B. eine
   mit Delphi erstellte Exe-Datei)
2. Ein Installations-Setup fr das gesamte Projekt (erstellt z.B. mit Inno-Setup)
3. Spezielle HTML-Vorlage fr die automatische Anpassung (s.u.)
4. Vorlage fr die Versionsinfo mit Downloadadresse
5. Fr eine bertragung per FTPS mssen vom Benutzer geeignte Zertifikatsdateien 
   eingebunden werden (siehe unten unter "FTP-Einstellungen")

HTML-Vorlage:
-------------
Es handelt sich dabei um eine gewhnliche HTML-Seite mit einigen speziellen
Erweiterungen und Platzhaltern. Diese werden bentigt, damit das Programm
VersionCopy an den gewnschten Stellen die aktuellen Informationen einsetzen kann.

Formateinstellungen:
format-date = <mode>
mode : 0 - internationales Datumsformat
       1 - deutsches Datumsformat
       2 - englisches Datumsformat
decimal-sep = <char>
       Standardmig wird als Dezimaltrenner fr die Grenangabe (s.u.) der Punkt
       verwendet. Mit <char> = , wird das auf das Komma umgestellt.
       
Platzhalter:
Ein Platzhalter hat die Form [%<pf-name>] und kann an beliebiger Stelle im HTML-Text
eingefgt werden. Er wird durch den Wert ersetzt, der ihm im Header zugewiesen
ist.
pf   : Projekt-Prfix (2 Buchstaben, in Versioncopy einstellbar)
name : version  - Versionsnummer (z.B. 5.1.3)
       date     - Datum der zur Bereitstellung (z.B. 12.10.2010)
       setup    - Name der Download-Datei (z.B. program-5.1.3.exe)
       size     - Gre der Download-Datei (z.B. 4,71 MB)
       md5      - MD5-Wert der Download-Datei (z.B. 4981dd3...)

Header:
Der HTML-Datei wird ein Header vorangestellt, der die Informationen fr alle
Platzhalter enthlt:
  <!-- #var
  <pf-name> = <wert>
  -->
VersionCopy passt die Werte im Header, die zu dem Projekt-Prfix passen,
automatisch an und ersetzt anschlieend die Platzhalter im Text durch die
aktuellen Werte.

Vorlage fr die Versionsinfo
----------------------------
Dabei handelt es sich um eine Textdatei mit 3 Zeilen:
1. Zeile: <Platzhalter fr Version> 
2. Zeile: <URL-Pfad fr Download>
3. Zeile: <Platzhalter fr Setup-Datei> 
Fest vorgeben muss man nur die 2. Zeile mit dem Downloadpfad, die anderen beiden
Zeilen werden vom Programm eingefgt.

Verfahrensweise:
----------------
Zunchst werden im interaktiven Modus mit dem Program geeignete Auftrge
erstellt und als Datei (Dateiname.vcj) gespeichert.
Mit der Taste "Testen" kann die Funktionsweise geprft werden, ohne dass
irgendwelche Daten tatschlich verndert oder kopiert werden. Der Ablauf wird
im Status-Fenster angezeigt und gleichzeitig auch in eine Protokolldatei
geschrieben ("<Name des Auftrags>.log" im Verzeichnis des Auftrags).
Wenn alles richtig aussieht, kann durch Klick auf die Taste "Starte Kopieren"
der Auftrag real ausgefhrt werden.

Aufruf ber die Befehlszeile (s.u.):
Der Kopiervorgang kann auch direkt ber die Befehlszeile gestartet werden:
<Pfad>\VersionCopy.exe <Auftrag> /force

Seite "Grund-Einstellungen":
----------------------------
Exe-Datei mit Versionsinfo:
Dies kann eine mit einer beliebigen Programmentwicklungsumgebung erstellte Datei
sein. Sie muss die blichen Versionsinformationen in ihren Ressourcen enthalten
(unter Delphi wird das ber die Projektoptionen eingestellt).

Setup-Datei:
Dies ist das mit einem Installer (z.B. Inno-Setup) erstellte Installationspaket,
das zum Download bereitgestellt werden soll.

Benutze Versionsebene:
Hier wird eingestellt, wie die Versionsinformation weiter gegeben werden soll.
Es sind maximal 4 Stufen mglich:
Setup-1, Setup-1.2, Setup1.2.03 oder Setup-1.2.0304

Vorversion behalten:
Hier wird eingestellt, welche im Downloadbereich befindlichen lteren Versionen
gelscht werden sollen. Wird z.B. Ebene 1 gewhlt, werden Setup-Dateien nur
dann erhalten wenn sich die erste Versionstufe ndert (setup-1... auf setup-2..).

Projekt-Prfix:
Hier wird die Projektkennzeichnung fr die Bearbeitung der HTML-Vorlagen
eingestellt (s.o.).

Seite "FTP-Einstellungen":
--------------------------
Hier werden die Zugangsdaten fr die verwendeten FTP-Server eingestellt.
Wenn eine sichere Verbindung per FTPS fr den Transfer verwendet werden soll,
mssen geeignete Zertifikate eingebunden werden. Dies geschieht ber die Datei
"certfiles.cfg", die beim Start des Programms geladen wird. Die angegebenen 
Dateien mssen sich im Installationsverzeichnis des Programms befinden.

Beispiel fr "certfiles.cfg":
[certificate]
RootCertFile = root.pem
CertFile     = cert.crt
KeyFile      = key.key
SSLPassword  = password

Die erforderlichen Zertifikats-Dateien knnen mit OpenSSL erstellt werden. Die
Textdatei "cert.cnf" enthlt die erforderlichen Voreinstellungen (siehe dazu die
Dokumentation zu OpenSSL).

Beispiel fr eine passende Batch-Datei:
openssl genrsa -des3 -out root.pem 1024
openssl req -config cert.cnf -new -out cert.csr
openssl rsa -in root.pem -out key.key
openssl x509 -in cert.csr -out cert.crt -req -signkey key.key -days 730
 
Seite "Dateien":
----------------
Versionsinfo-Datei: Textdatei mit den aktuellen Versionsinformationen (s.o.)
Setup-Datei mit Version: Setup mit Versionsnummer (wird vom Programm erzeugt)
Erstelle Datei mit MD5-Checksumme: Auswhlen, wenn der MD5-Wert in eine Datei
  "<Setupname>.md5" geschrieben werden soll
Erstelle OpenPGP-Signatur: Diese Option ist verfgbar, wenn GnuPG installiert ist
  und erzeugt eine Datei "<Setupname.exe>.sig".   
Zustzliche Dateien:
Hier knnen beliebige Dateien, z.B. solche mit Update-Informationen ausgewhlt
werden, die zum Download bereitgestellt werden sollen. Auf Wunsch kann den Dateien
automatisch das Projekt-Prfix vorangestellt werden.

Ziele:
------
Verzeichnisse:
Hier knnen beliebige Verzeichnisse im Windows-Dateisystem ausgewhlt werden,
in die die oben genannten Dateien und das Setup kopiert werden sollen. Die
Versionsinformation wird nur in die markierten Verzeichnisse kopiert.

Ziele auf FTP-Server:
Hier knnen beliebige Verzeichnisse auf den oben festgelegten FTP-Servern
ausgewhlt werden, in die die Dateien und das Setup kopiert werden sollen. Die
Versionsinformation wird nur in die markierten Verzeichnisse kopiert.

HTML-Seiten:
------------
Es werden die HTML-Vorlagen (siehe Beispiel unten) ausgewhlt, die vom
vom Programm aktualisiert und per FTP in die ausgewhlten Verzeichnisse kopiert
werden.

Befehlszeilenoptionen:
----------------------
Fr den Aufruf aus einer Batch-Datei (oder auch ber den Befehle "Ausfhren" im
Windows-Startmen) stehen einige Befehlszeilenoptionen zur Verfgung.
Programmaufruf: FtpCopy <Auftrag> [Optionen]
  <Auftrag>   - Name der Auftragsdatei (siehe oben)
                Enthlt der Name Leerzeichen, muss er durch Anfhrungszeichen
                umschlossen sein.
  Optionen    - Werden keine Optionen angegeben, ffnet sich das Programmfenster
                mit dem in dem Aufruf enthaltenen Auftrag
    /force    - Der in dem Aufruf enthaltene Auftrag wird sofort ausgefhrt
    /test     - Der in dem Aufruf enthaltene Auftrag wird sofort getestet (s.o.)
    /continue - Das Status-Fenster wird automatisch geschlossen
    /append   - Das Protokoll wird an eine vorhandene Datei angehngt

J. Rathlev, Februar 2018

Anhang
======
Beispiel - Verteilung von Personal Backup:
------------------------------------------
1. Mit Delphi wird die Programm-Datei "PersBackup.exe" erstellt.
2. Mit Inno-Setup wird das Installationspaket erstellt.
3. Mit 7-Zip wird ein Update-Archiv mit der neuen Programmversion erstellt.
4. Mit VersionCopy wird alles verteilt.

Der gesamte Prozess kann ber eine Batch Datei gesteuert werden:
pb-make-setup.cmd
-----------------
  echo Erzeugen der Archive fr die Distribution von PersBackup 5.1
  rem Aufruf: PBSETUP

  rem Sprachen einbinden
  echo Sprachdateien aktualisieren
  copy /y ..\languages\de\default.mo ..\Release\win32\locale\de\LC_MESSAGES\
  ... (weitere Sprachen)
  
  echo.
  echo InnoSetup starten
  "%ProgramFiles%\Inno Setup 5\Compil32.exe" /cc pb5.iss
  echo InnoSetup fertig

  rem Archiv fr Update
  "%ProgramFiles%\7-Zip\7z.exe" u -r pb-update-5.zip @pb-files.txt

  rem Setup versionieren und verteilen
  "...\VersionCopy.exe" PersBackup-5.vcj /f

  pause

Vorlage fr Versionsinfo: (pb-setup-5.ver)
-------------------------
  5.9.2.1
  
Vorlage fr Downloadort: (pb-setup-5.loc)
------------------------
  http://personal-backup.rathlev-home.de/download/
  pb-setup-5.9.0201.exe 
  
Vorlage fr HTML-Seite:
-----------------------
  <!-- #var
  date-format = 0 // 0 = ISO, 1 = German, 2 = English
  decimal-sep = ,
  
  pb-vers = 4.5.5.1   
  pb-date = 15.4.2011   
  pb-setup = pb-setup-4.5.0501.exe   
  pb-size = 5,54 MB   
  pb-md5 = fb71c5e5a671f3c75066bb8f7e8de3f9   
  
  pb5-vers = 5.9.2.1   
  pb5-date = 15.2.2018   
  pb5-setup = pb-setup-5.9.0201.exe   
  pb5-size = 15,47 MB   
  pb5-md5 = a300e3ba0def888d5115a0ca3b24b024   

  -->
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  <html>
  <head>
   ...
  </head>

  <body>
   ...
  <h3>Download der Windows-Installation:</h3>
  <p><b>Vers. [%pb5-vers]</b> vom [%pb5-date]</p>
  <table>
    <tr>
      <td>
        <a href="http://www.ieap.uni-kiel.de/surface/ag-berndt/download/utilities/[%pb5-setup]" title="Installation Vers. 5">
          <img src="images/ball-r.gif" width="14" height="14" align="middle" border="0">
          <b>Server der Uni-Kiel</b></a>
      </td>
      <td>
        <a href="download/[%pb5-setup]" title="Installation">
          <img src="images/ball-r.gif" width="14" height="14" align="middle">
          bei <b>rathlev-home.de  ([%pb5-size])</b></a>
      </td>
    </tr>
    <tr>
     <td colspan="2"><div style="margin-top:-5px;text-indent:1.5em;">
       (MD5-Checksumme: [%pb5-md5])</div></td>
  </tr>
  </table>
   ...
  </body>
  </html>

J. Rathlev, April 2018
