xsl-validator/BUILD.md

# DocuMentor Build-Anleitung

## Voraussetzungen

```bash
# 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

```bash
# 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`

### Manuelle Build-Schritte

```bash
# 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

```bash
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:

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

### Schritt 3: MSI kompilieren

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

### Schritt 4: MSI testen

```bash
# 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:

```bash
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)

1. **GUID generieren** für `installer.iss` (nur beim ersten Mal!):
   ```bash
   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.

2. **Windows-Build erstellen**:
   ```bash
   uv run python build_windows.py
   ```

3. **Installer kompilieren**:
   ```bash
   iscc installer.iss
   ```

4. **Ergebnis**:
   - `dist/installer/DocuMentor-Setup-0.1.0.exe` (mit Icon und Versionsinformationen)

## Konfiguration anpassen

### Icon anpassen

**Option 1: Standard-Icon generieren**
```bash
uv run python create_icon.py
```

**Option 2: Eigenes Icon aus PNG erstellen**
```bash
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

Versionsinformationen werden automatisch aus `pyproject.toml` generiert:

```bash
uv run python create_version_info.py
```

**Version ändern:**

In `pyproject.toml`:
```toml
version = "0.2.0"
```

Auch aktualisieren in:
- `installer.iss` (Zeile 13: `#define MyAppVersion`)

Dann Versionsinformationen neu generieren:
```bash
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:
```python
excludes=[
    'tkinter',
    'matplotlib',
    'test',
    'unittest',
],
```

### One-File Build (alles in einer .exe)

In `DocuMentor.spec` ändern:
```python
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)

```bash
# Build erstellen
uv run python build_windows.py

# Mit Wine testen
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 A** — Einfache Python-Module: Hidden imports in `DocuMentor.spec` ergänzen:
```python
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:
```python
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**:
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:
```python
datas=ui_files,  # Muss gesetzt sein
```

Im Code müssen Ressource-Pfade PyInstaller-kompatibel aufgelöst werden:
```python
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)

```yaml
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

```bash
#!/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):

1. **Java Runtime Environment (JRE) 11+** — Für Saxon und Apache FOP (https://adoptium.net/)
2. **Apache FOP** — XSL-FO zu PDF Konvertierung (https://xmlgraphics.apache.org/fop/)
3. **Saxon XSLT Prozessor** — XSLT 2.0/3.0 Transformationen (https://www.saxonica.com/)
4. **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:
1. `pyproject.toml` — `version = "X.Y.Z"`
2. `installer.iss` — `#define MyAppVersion "X.Y.Z"`

Dann Versionsinformationen neu generieren:
```bash
uv run python create_version_info.py
```

## Lizenz und Rechtliches

- PySide6 (LGPL): Dynamische Verlinkung ist OK
- Polars (MIT): Unproblematisch
- Pydantic (MIT): Unproblematisch

Externe Tools (Saxon, FOP) haben eigene Lizenzen und müssen separat installiert werden.