Files

T

Vitali Graf ef2ec13ff8 Docs: WiX-Version in BUILD.md auf v6 fixiert und OSMF-EULA-Hinweis ergänzt

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-20 12:47:24 +02:00

9.9 KiB

Raw Permalink Blame History

DocuMentor Build-Anleitung

Voraussetzungen

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

Für MSI-Installer zusätzlich:

WiX Toolset v6: dotnet tool install --global wix --version 6.*

Hinweis: WiX v7+ erfordert die Akzeptanz der OSMF-EULA (wix eula accept). WiX v6 vermeidet diese Einschränkung.

Für Setup.exe zusätzlich:

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

Schnellstart: ZIP-Distribution erstellen

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

Dies erstellt automatisch:

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

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

MSI-Installer erstellen (WiX Toolset)

Schritt 1: PyInstaller Build erstellen

uv run python build_windows.py

Schritt 2: ProductFiles.wxs generieren

WICHTIG: WiX v6 hat das heat Tool entfernt. Stattdessen wird ein Python-Skript verwendet:

# Generiert automatisch ProductFiles.wxs mit allen Dateien aus dist/DocuMentor
uv run python generate_wix_files.py

Schritt 3: MSI kompilieren

wix build DocuMentor.wxs ProductFiles.wxs -o DocuMentor.msi

Schritt 4: MSI testen

# Installation (als Administrator)
msiexec /i DocuMentor.msi

# Silent Installation für Deployment
msiexec /i DocuMentor.msi /quiet /qn /norestart

# Deinstallation
msiexec /x DocuMentor.msi

MSI-Vorteile

Windows-Standard (.msi Format)
Gruppen-Richtlinien-Deployment (GPO) für Enterprise
Silent Installation (msiexec /quiet)
Windows Installer Transaktionen und Rollback
Patch-Unterstützung (.msp für Updates)
Versionsupgrades automatisch verwaltet

MSI-Build automatisieren

Alternativ zu den manuellen Schritten kann ein build_msi.py Skript verwendet werden:

uv run python build_msi.py

Dieses Skript führt generate_wix_files.py und wix build automatisch nacheinander aus.

Setup.exe erstellen (Inno Setup)

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.
Windows-Build erstellen:
```
uv run python build_windows.py
```
Installer kompilieren:
```
iscc installer.iss
```
Ergebnis:
- dist/installer/DocuMentor-Setup-0.1.0.exe (mit Icon und Versionsinformationen)

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

Icon erstellen oder downloaden (.ico Format mit mehreren Größen)
Als resources/icon.ico speichern
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

Versionsinformationen werden automatisch aus pyproject.toml generiert:

uv run python create_version_info.py

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 (Linux/WSL)

# Build erstellen
uv run python build_windows.py

# Mit Wine testen
wine dist/DocuMentor/DocuMentor.exe

Testing auf Windows

ZIP-Datei auf Windows-System kopieren
Entpacken
DocuMentor.exe starten
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 A — Einfache Python-Module: Hidden imports in DocuMentor.spec ergänzen:

hiddenimports=[
    'missing_module',
]

Lösung B — Packages mit nativen Extensions (Rust/C, z.B. connectorx): hiddenimports allein reicht nicht, da PyInstaller die __init__.py ins PYZ-Archiv packt, aber die .pyd-Extension separat im Dateisystem erwartet. Stattdessen collect_all verwenden:

from PyInstaller.utils.hooks import collect_all
cx_datas, cx_binaries, cx_hiddenimports = collect_all('problematic_package')

a = Analysis(
    # ...
    binaries=cx_binaries,
    datas=cx_datas,
    hiddenimports=cx_hiddenimports,
)

Antivirus blockiert die .exe

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

Lösungen:

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

Executable ist zu groß (>200 MB)

Lösungen:

UPX-Kompression ist bereits aktiv
Ungenutzte Module excluden (siehe oben)
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

Im Code müssen Ressource-Pfade PyInstaller-kompatibel aufgelöst werden:

import sys
from pathlib import Path

if hasattr(sys, "_MEIPASS"):
    res_path = Path(sys._MEIPASS) / "res" / "data.sql"
else:
    res_path = Path(__file__).parents[3] / "src" / "res" / "data.sql"

Automatisierung

GitHub Actions (CI/CD)

name: Build Windows Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install uv
        uses: astral-sh/setup-uv@v1

      - name: Build
        run: uv run python build_windows.py

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: dist/*.zip

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"

Distributions-Formate im Vergleich

	ZIP	Setup.exe (Inno Setup)	MSI (WiX)
Portabel	Ja	Nein	Nein
Installation nötig	Nein	Ja	Ja
Deinstallation	Nein	Ja	Ja
Start-Menü	Nein	Ja	Ja
GPO-Deployment	Nein	Nein	Ja
Silent Install	—	Ja	Ja
Rollback	—	Nein	Ja
Patch-Support	—	Nein	Ja (.msp)

Externe Abhängigkeiten

DocuMentor benötigt diese Tools (NICHT im Installer enthalten):

Java Runtime Environment (JRE) 11+ — Für Saxon und Apache FOP (https://adoptium.net/)
Apache FOP — XSL-FO zu PDF Konvertierung (https://xmlgraphics.apache.org/fop/)
Saxon XSLT Prozessor — XSLT 2.0/3.0 Transformationen (https://www.saxonica.com/)
diff-pdf — PDF-Vergleich (https://vslavik.github.io/diff-pdf/)

Nach der Installation müssen die Pfade zu diesen Tools in den DocuMentor-Einstellungen konfiguriert werden.

Dokumentation für Endbenutzer

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

Installationsanweisungen
Liste der externen Abhängigkeiten
Konfigurationshinweise

Versionierung

Version in folgenden Dateien aktualisieren:

pyproject.toml — version = "X.Y.Z"
installer.iss — #define MyAppVersion "X.Y.Z"