info/xsl-validator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Docs: BUILD.md mit windows_distribution.md konsolidiert und Einzeldatei entfernt

Browse Source 
Gesamte Windows-Distribution-Dokumentation (ZIP, Setup.exe, MSI) in BUILD.md
zusammengeführt. docs/windows_distribution.md entfernt, da redundant.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Vitali Graf
2026-03-15 19:37:10 +01:00
parent 36911b111d
commit bd6827cb2f
2 changed files with 156 additions and 462 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BUILD.md
+156 -58
View File
@@ -1,15 +1,19 @@
# DocuMentor Build-Anleitung
## Schnellstart: Windows-Distribution erstellen
### Voraussetzungen
## Voraussetzungen
```bash
# Dependencies installieren (inkl. Pillow für Icon-Generierung)
# Dependencies installieren (inkl. Pillow für Icon-Generierung und PyInstaller)
uv sync --all-groups
```
### Build ausführen
Für MSI-Installer zusätzlich:
- **WiX Toolset v6**: `dotnet tool install --global wix`
Für Setup.exe zusätzlich:
- **Inno Setup**: https://jrsoftware.org/isdl.php
## Schnellstart: ZIP-Distribution erstellen
```bash
# Automatischer Build (empfohlen)
@@ -22,16 +26,6 @@ Dies erstellt automatisch:
3. **Executable**: `dist/DocuMentor/DocuMentor.exe` (mit Icon und Versionsinformationen)
4. **ZIP-Archiv**: `dist/DocuMentor-YYYYMMDD-Windows.zip`
### Icon anpassen (optional)
```bash
# 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
```bash
@@ -46,13 +40,64 @@ uv run pyinstaller --clean DocuMentor.spec
# Mit Wine: wine dist/DocuMentor/DocuMentor.exe
```
## Setup.exe erstellen (optional)
## MSI-Installer erstellen (WiX Toolset)
### Mit Inno Setup
### Schritt 1: PyInstaller Build erstellen
1. **Inno Setup installieren**: https://jrsoftware.org/isdl.php
```bash
uv run python build_windows.py
```
2. **GUID generieren** für `installer.iss` (nur beim ersten Mal!):
### 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
```
@@ -61,25 +106,19 @@ uv run pyinstaller --clean DocuMentor.spec
**WICHTIG**: Die GUID nur EINMAL generieren! Bei Updates dieselbe GUID verwenden.
3. **Windows-Build erstellen**:
2. **Windows-Build erstellen**:
```bash
uv run python build_windows.py
```
Dies erstellt automatisch das Icon und kopiert es nach `dist/DocuMentor/`.
4. **Installer kompilieren**:
3. **Installer kompilieren**:
```bash
iscc installer.iss
```
5. **Ergebnis**:
4. **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
@@ -110,16 +149,12 @@ Das Icon wird automatisch verwendet für:
### Versionsinformationen
**Automatische Generierung:**
Versionsinformationen werden automatisch aus `pyproject.toml` generiert:
```bash
uv run python create_version_info.py
```
Dies liest die Version aus `pyproject.toml` und erstellt `version_info.txt`.
**Version ändern:**
In `pyproject.toml`:
@@ -177,13 +212,13 @@ exe = EXE(
## Testing
### Lokales Testing
### Lokales Testing (Linux/WSL)
```bash
# Build erstellen
uv run python build_windows.py
# Mit Wine testen (Linux/WSL)
# Mit Wine testen
wine dist/DocuMentor/DocuMentor.exe
```
@@ -205,13 +240,27 @@ wine dist/DocuMentor/DocuMentor.exe
### "Module not found" beim Start
**Lösung**: Hidden imports in `DocuMentor.spec` ergänzen:
**Lösung A** — Einfache Python-Module: Hidden imports in `DocuMentor.spec` ergänzen:
```python
hiddenimports=[
'missing.module',
'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.
@@ -237,11 +286,46 @@ hiddenimports=[
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)
Siehe `docs/windows_distribution.md` für vollständiges Beispiel.
```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
@@ -268,30 +352,29 @@ echo " • ZIP: dist/DocuMentor-*-Windows.zip"
echo " • Setup: dist/installer/DocuMentor-Setup-$VERSION.exe"
```
## Distribution
## Distributions-Formate im Vergleich
### ZIP-Archiv
| | 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) |
**Vorteile:**
- Einfach, portable
- Keine Installation nötig
- USB-Stick-fähig
## Externe Abhängigkeiten
**Verwendung:**
- Auf GitHub Releases hochladen
- Per E-Mail versenden
- Auf Webserver bereitstellen
DocuMentor benötigt diese Tools (NICHT im Installer enthalten):
### Setup.exe
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/)
**Vorteile:**
- Professionell
- Start-Menü-Integration
- Deinstallation
**Verwendung:**
- Primäre Distributions-Methode
- Auf Website zum Download anbieten
Nach der Installation müssen die Pfade zu diesen Tools in den DocuMentor-Einstellungen konfiguriert werden.
## Dokumentation für Endbenutzer
@@ -300,6 +383,21 @@ Die `dist/DocuMentor/README.txt` wird automatisch erstellt und enthält:
- Liste der externen Abhängigkeiten
- Konfigurationshinweise
## Weitere Informationen
## Versionierung
Siehe `docs/windows_distribution.md` für detaillierte Dokumentation.
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.