xsl-validator/BUILD.md

DocuMentor Build-Anleitung

Schnellstart: Windows-Distribution erstellen

Voraussetzungen

# Dependencies installieren (inkl. Pillow für Icon-Generierung)
uv sync --all-groups

Build ausführen

# Automatischer Build (empfohlen)
uv run python build_windows.py

Dies erstellt automatisch:

1. Icon (falls nicht vorhanden): resources/icon.ico
2. Versionsinformationen: version_info.txt
3. Executable: dist/DocuMentor/DocuMentor.exe (mit Icon und Versionsinformationen)
4. ZIP-Archiv: dist/DocuMentor-YYYYMMDD-Windows.zip

Icon anpassen (optional)

# Standard-Icon generieren
uv run python create_icon.py

# Oder eigenes PNG-Icon konvertieren
uv run python create_icon.py mein-logo.png

Manuelle Build-Schritte

# 1. Cleanup
rm -rf build/ dist/

# 2. PyInstaller ausführen
uv run pyinstaller --clean DocuMentor.spec

# 3. Testen
# Auf Windows: dist/DocuMentor/DocuMentor.exe
# Mit Wine: wine dist/DocuMentor/DocuMentor.exe

Setup.exe erstellen (optional)

Mit Inno Setup

1. Inno Setup installieren: https://jrsoftware.org/isdl.php

2. GUID generieren für installer.iss (nur beim ersten Mal!):

   uv run python generate_guid.py
   

   Kopiere die generierte GUID und füge sie in installer.iss bei AppId ein (Zeile ~22).

   WICHTIG: Die GUID nur EINMAL generieren! Bei Updates dieselbe GUID verwenden.

3. Windows-Build erstellen:

   uv run python build_windows.py
   

   Dies erstellt automatisch das Icon und kopiert es nach dist/DocuMentor/.

4. Installer kompilieren:

   iscc installer.iss
   

5. Ergebnis:

   • dist/installer/DocuMentor-Setup-0.1.0.exe (mit Icon und Versionsinformationen)

MSI erstellen (optional)

Mit WiX Toolset - noch zu implementieren.

Konfiguration anpassen

Icon anpassen

Option 1: Standard-Icon generieren

uv run python create_icon.py

Option 2: Eigenes Icon aus PNG erstellen

uv run python create_icon.py ihr-logo.png

Option 3: Manuell ICO-Datei platzieren

1. Icon erstellen oder downloaden (.ico Format mit mehreren Größen)
2. Als resources/icon.ico speichern
3. Beim nächsten Build wird es automatisch verwendet

Das Icon wird automatisch verwendet für:

• Windows-Executable (DocuMentor.exe)
• Inno Setup Installer
• Desktop-Verknüpfungen

Anforderungen:

• Multi-Size ICO (16x16 bis 256x256 Pixel)
• Das create_icon.py Skript erstellt alle Größen automatisch

Versionsinformationen

Automatische Generierung:

Versionsinformationen werden automatisch aus pyproject.toml generiert:

uv run python create_version_info.py

Dies liest die Version aus pyproject.toml und erstellt version_info.txt.

Version ändern:

In pyproject.toml:

version = "0.2.0"

Auch aktualisieren in:

• installer.iss (Zeile 13: #define MyAppVersion)

Dann Versionsinformationen neu generieren:

uv run python create_version_info.py

Was enthalten die Versionsinformationen:

• Dateiversion und Produktversion
• Beschreibung und Copyright
• Anwendungsname
• Wird in Windows Explorer angezeigt (Rechtsklick → Eigenschaften → Details)

Build-Größe reduzieren

In DocuMentor.spec Module ausschließen:

excludes=[
    'tkinter',
    'matplotlib',
    'test',
    'unittest',
],

One-File Build (alles in einer .exe)

In DocuMentor.spec ändern:

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,      # Uncomment
    a.zipfiles,      # Uncomment
    a.datas,         # Uncomment
    [],              # Comment out
    exclude_binaries=False,  # Ändern
    # ...
    name='DocuMentor',
    onefile=True,    # Hinzufügen
)

# COLLECT auskommentieren oder entfernen

Achtung: One-File ist langsamer beim Start (3-5 Sekunden).

Testing

Lokales Testing

# Build erstellen
uv run python build_windows.py

# Mit Wine testen (Linux/WSL)
wine dist/DocuMentor/DocuMentor.exe

Testing auf Windows

1. ZIP-Datei auf Windows-System kopieren
2. Entpacken
3. DocuMentor.exe starten
4. Features testen:
   • Programmstart
   • Einstellungsdialog öffnet beim ersten Start
   • Projekt öffnen/erstellen
   • Tree-Navigation
   • XSL/XML-Dateien hinzufügen
   • PDF-Generierung (mit konfigurierten Tools)
   • PDF-Vergleich

Troubleshooting

"Module not found" beim Start

Lösung: Hidden imports in DocuMentor.spec ergänzen:

hiddenimports=[
    'missing.module',
]

Antivirus blockiert die .exe

Ursache: Unsigned executables werden oft als verdächtig eingestuft.

Lösungen:

1. Code-Signing-Zertifikat kaufen und verwenden
2. Bei Microsoft SmartScreen einreichen
3. Exception in Antivirus eintragen (für Tests)

Executable ist zu groß (>200 MB)

Lösungen:

1. UPX-Kompression ist bereits aktiv
2. Ungenutzte Module excluden (siehe oben)
3. Virtual Environment aufräumen: uv sync --no-dev

UI-Dateien nicht gefunden

Problem: .ui Dateien werden nicht gefunden.

Lösung: In DocuMentor.spec prüfen:

datas=ui_files,  # Muss gesetzt sein

Automatisierung

GitHub Actions (CI/CD)

Siehe docs/windows_distribution.md für vollständiges Beispiel.

Lokales Release-Skript

#!/bin/bash
# release.sh - Erstellt vollständiges Release

VERSION="0.1.0"

echo "Building DocuMentor v$VERSION..."

# 1. Build
uv run python build_windows.py

# 2. Installer (falls Inno Setup installiert)
if command -v iscc &> /dev/null; then
    iscc installer.iss
    echo "✓ Installer erstellt"
fi

echo ""
echo "Release v$VERSION fertig!"
echo "  • ZIP: dist/DocuMentor-*-Windows.zip"
echo "  • Setup: dist/installer/DocuMentor-Setup-$VERSION.exe"

Distribution

ZIP-Archiv

Vorteile:

• Einfach, portable
• Keine Installation nötig
• USB-Stick-fähig

Verwendung:

• Auf GitHub Releases hochladen
• Per E-Mail versenden
• Auf Webserver bereitstellen

Setup.exe

Vorteile:

• Professionell
• Start-Menü-Integration
• Deinstallation

Verwendung:

• Primäre Distributions-Methode
• Auf Website zum Download anbieten

Dokumentation für Endbenutzer

Die dist/DocuMentor/README.txt wird automatisch erstellt und enthält:

• Installationsanweisungen
• Liste der externen Abhängigkeiten
• Konfigurationshinweise

Weitere Informationen

Siehe docs/windows_distribution.md für detaillierte Dokumentation.