14 KiB

Raw Blame History

PointCab Renamer - Deployment-Anleitung

Version 4.2.1 | Datum: 16. Januar 2026

Build-Status (Testergebnisse 2026-01-16)

Build-Methode	Status	Hinweise
`build_windows.bat`	✅ Funktioniert	Empfohlen auf Windows
`build_linux.sh`	✅ Getestet	Funktioniert auf Ubuntu 20.04+
`build_windows_wine.sh`	⚠️ Experimentell	Fehlschläge auf Headless-Servern möglich
`build_windows_on_linux.sh`	⚠️ Docker	Nicht in Docker-in-Docker möglich

Übersicht

Diese Anleitung beschreibt, wie Sie aus dem Python-Quellcode ausführbare Dateien für Windows (.exe) und Ubuntu (Binary) erstellen.

Voraussetzungen

Benötigte Software

Komponente	Windows	Ubuntu
Python	3.8+	3.8+
PyInstaller	5.0+	5.0+
tkinter	(in Python enthalten)	`python3-tk`

Installation der Voraussetzungen

Windows

Python installieren:
- Laden Sie Python von https://www.python.org/downloads/ herunter
- Bei der Installation: ☑ "Add Python to PATH" aktivieren
PyInstaller installieren:
```
pip install pyinstaller
```

Ubuntu

Python und tkinter installieren:

sudo apt update
sudo apt install python3 python3-pip python3-tk

PyInstaller installieren:
```
pip3 install pyinstaller
```

Windows-Build (.exe)

Automatisch (empfohlen)

Öffnen Sie eine Eingabeaufforderung (cmd)
Navigieren Sie zum Projektordner:
```
cd C:\Pfad\zum\pointcab_renamer
```
Führen Sie das Build-Skript aus:
```
build_windows.bat
```
Die fertige .exe finden Sie im Ordner dist\pointcab_renamer\

Manuell

Öffnen Sie eine Eingabeaufforderung
Navigieren Sie zum Quellcode-Ordner

Führen Sie PyInstaller aus:

pyinstaller --onefile --windowed --name "PointCab_Renamer" ^<br>     --add-data "cluster_cleanup.txt;." ^<br>     pointcab_renamer.py

Die .exe befindet sich in dist\PointCab_Renamer.exe

PyInstaller-Optionen erklärt

Option	Beschreibung
`--onefile`	Alles in eine einzige .exe packen
`--windowed`	Kein Konsolenfenster anzeigen
`--name`	Name der Ausgabedatei
`--add-data`	Zusätzliche Dateien einbinden
`--icon`	(Optional) Icon-Datei (.ico)

Bekannte Probleme unter Windows

Problem: Antivirus blockiert die .exe

Lösung: Die erstellte .exe als Ausnahme hinzufügen oder signieren.

Problem: "DLL nicht gefunden"

Lösung: Visual C++ Redistributable installieren.

Ubuntu-Build (Binary)

Automatisch (empfohlen)

Öffnen Sie ein Terminal
Navigieren Sie zum Projektordner:
```
cd /pfad/zum/pointcab_renamer
```
Machen Sie das Build-Skript ausführbar und führen Sie es aus:
```
chmod +x build_linux.sh
./build_linux.sh
```
Das fertige Binary finden Sie im Ordner dist/

Manuell

Öffnen Sie ein Terminal
Navigieren Sie zum Quellcode-Ordner

Führen Sie PyInstaller aus:

pyinstaller --onefile --name "pointcab_renamer" \
  --add-data "cluster_cleanup.txt:." \
  pointcab_renamer.py

Das Binary befindet sich in dist/pointcab_renamer
Machen Sie es ausführbar:
```
chmod +x dist/pointcab_renamer
```

Bekannte Probleme unter Ubuntu

Problem: "No display name and no $DISPLAY environment variable"

Lösung: Das Binary muss in einer grafischen Umgebung gestartet werden, nicht über SSH.

Problem: "_tkinter not found"

Lösung: sudo apt install python3-tk

Cross-Compilation: Windows .exe unter Linux erstellen

Es gibt mehrere Möglichkeiten, eine Windows .exe unter Linux zu erstellen, ohne Windows zu installieren.

Methode 1: Docker (Empfohlen)

Die Docker-Methode ist die zuverlässigste und reproduzierbarste Option.

Voraussetzungen

Docker installieren:

sudo apt update
sudo apt install docker.io
sudo systemctl start docker
sudo systemctl enable docker

Benutzer zur docker-Gruppe hinzufügen:

sudo usermod -aG docker $USER
# Danach neu einloggen oder:
newgrp docker

Docker-Installation testen:
```
docker run hello-world
```

Verwendung

Navigieren Sie zum Projektordner:
```
cd /pfad/zum/pointcab_renamer
```
Führen Sie das Build-Skript aus:
```
./build_windows_on_linux.sh
```
Die fertige .exe befindet sich in dist/PointCab_Renamer.exe

Was das Skript macht

Prüft Docker-Installation und -Status
Lädt das cdrx/pyinstaller-windows Docker-Image (beim ersten Mal)
Startet einen Container mit Windows-Umgebung
Führt PyInstaller im Container aus
Kopiert die .exe und Zusatzdateien nach dist/

Vorteile der Docker-Methode

✅ Zuverlässig und reproduzierbar
✅ Isolierte Build-Umgebung
✅ Keine manuelle Windows-Python-Installation
✅ Gleiche Ergebnisse wie auf echtem Windows
✅ Einfach in CI/CD-Pipelines integrierbar

Troubleshooting Docker

Problem: "Permission denied" beim Docker-Aufruf

Lösung:

sudo usermod -aG docker $USER
# Neu einloggen erforderlich!

Problem: Docker-Image-Download schlägt fehl

Lösung: Proxy-Einstellungen prüfen oder manuell herunterladen:

docker pull cdrx/pyinstaller-windows:python3

Problem: Container startet nicht

Lösung: Docker-Daemon prüfen:

sudo systemctl status docker
sudo systemctl restart docker

Methode 2: Wine (Fallback)

Die Wine-Methode ist weniger zuverlässig, kann aber ohne Docker verwendet werden.

Voraussetzungen

Wine installieren:

sudo dpkg --add-architecture i386
sudo apt update
sudo apt install wine64 wine32

Installation prüfen:
```
wine --version
```

Verwendung

Navigieren Sie zum Projektordner:
```
cd /pfad/zum/pointcab_renamer
```
Führen Sie das Build-Skript aus:
```
./build_windows_wine.sh
```
Das Skript installiert automatisch:
- Windows-Python in Wine
- PyInstaller

Einschränkungen der Wine-Methode

⚠️ Nicht alle Windows-Funktionen werden unterstützt
⚠️ Kann bei komplexen Abhängigkeiten fehlschlagen
⚠️ Langsamerer Build-Prozess
⚠️ Ergebnisse können von echter Windows-Build abweichen

Methode 3: GitHub Actions (Automatisiert)

Für regelmäßige Builds können Sie GitHub Actions verwenden.

Erstellen Sie .github/workflows/build.yml:

name: Build Windows Executable

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:

jobs:
  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      
      - name: Install dependencies
        run: pip install pyinstaller
      
      - name: Build executable
        run: |
          pyinstaller --onefile --windowed --name "PointCab_Renamer" `
            --add-data "cluster_cleanup.txt;." `
            --add-data "BENUTZERHANDBUCH.md;." `
            pointcab_renamer.py          
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: PointCab_Renamer_Windows
          path: |
            dist/PointCab_Renamer.exe
            cluster_cleanup.txt
            BENUTZERHANDBUCH.md

Vergleich der Cross-Compilation-Methoden

Methode	Zuverlässigkeit	Geschwindigkeit	Aufwand
Docker	⭐⭐⭐⭐⭐	⭐⭐⭐	Niedrig
Wine	⭐⭐	⭐⭐	Mittel
GitHub Actions	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	Niedrig
Echtes Windows	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	Hoch (VM)

Empfehlung: Verwenden Sie die Docker-Methode für lokale Builds und GitHub Actions für automatisierte Release-Builds.

Testen der Executables

Windows-Test

Kopieren Sie die .exe und cluster_cleanup.txt in einen Testordner
Doppelklicken Sie auf die .exe
Das Hauptmenü sollte erscheinen
Testen Sie alle drei Modi mit einem Testprojekt

Ubuntu-Test

Kopieren Sie das Binary und cluster_cleanup.txt in einen Testordner
Starten Sie das Programm:
```
./pointcab_renamer
```
Das Hauptmenü sollte erscheinen
Testen Sie alle drei Modi mit einem Testprojekt

Checkliste für Tests

Programm startet ohne Fehler
Hauptmenü wird angezeigt
LSDX-Datei kann ausgewählt werden
PointCloud-Ordner wird erkannt
Vorschau wird korrekt angezeigt
Umbenennung funktioniert
LSDX wird aktualisiert
Log-Datei wird erstellt
Batch-Modus funktioniert
Merger funktioniert

Distribution an Mitarbeiter

Bereitstellung

Für Windows:
- Kopieren Sie diese Dateien in einen Ordner:
  - PointCab_Renamer.exe
  - cluster_cleanup.txt
  - BENUTZERHANDBUCH.md (oder als PDF)
- Erstellen Sie ein ZIP-Archiv
- Verteilen Sie über Netzlaufwerk oder E-Mail
Für Ubuntu:
- Kopieren Sie diese Dateien in einen Ordner:
  - pointcab_renamer
  - cluster_cleanup.txt
  - BENUTZERHANDBUCH.md
- Erstellen Sie ein tar.gz-Archiv:
```
tar -czvf pointcab_renamer_linux.tar.gz pointcab_renamer cluster_cleanup.txt BENUTZERHANDBUCH.md
```
- Verteilen Sie über Netzlaufwerk

Empfohlene Ordnerstruktur für Mitarbeiter

PointCab_Renamer/
├── PointCab_Renamer.exe (oder pointcab_renamer für Linux)
├── cluster_cleanup.txt
├── BENUTZERHANDBUCH.md
└── logs/  (wird automatisch erstellt)

Updates verteilen

Erstellen Sie die neue Executable
Informieren Sie die Mitarbeiter über Änderungen (CHANGELOG)
Mitarbeiter ersetzen die alte .exe durch die neue
cluster_cleanup.txt kann beibehalten werden (falls angepasst)

Troubleshooting beim Build

"ModuleNotFoundError"

Lösung: Fehlende Module installieren:

pip install <modulname>

"Hidden import not found"

Lösung: Hidden imports hinzufügen:

pyinstaller --hidden-import=<modulname> ...

"Executable zu groß" (>100MB)

Lösung: UPX-Kompression aktivieren:

pip install upx
pyinstaller --onefile --upx-dir=/pfad/zu/upx ...

"tkinter funktioniert nicht"

Windows: tkinter ist normalerweise in Python enthalten. Reinstallieren Sie Python mit der "tcl/tk" Option.

Ubuntu: Installieren Sie python3-tk:

sudo apt install python3-tk

Versionskontrolle

Bei jeder neuen Version:

Version im Quellcode aktualisieren (VERSION = "4.2" etc.)
CHANGELOG.md aktualisieren
Neue Builds für Windows und Ubuntu erstellen
Builds testen

Im Git-Repository taggen:

git tag -a v4.2 -m "Version 4.2"
git push origin v4.2

Troubleshooting: Docker-Probleme

Docker ist nicht installiert

Ubuntu/Debian:

sudo apt update
sudo apt install docker.io
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER
# Dann neu einloggen oder: newgrp docker

Fedora/RHEL:

sudo dnf install docker
sudo systemctl start docker

Docker-Daemon startet nicht

Symptom: Cannot connect to the Docker daemon

Lösungen:

Service starten:
```
sudo systemctl start docker
```
Status prüfen:
```
sudo systemctl status docker
```
Logs prüfen:
```
sudo journalctl -u docker.service
```

Berechtigung verweigert

Symptom: permission denied while trying to connect to the Docker daemon

Lösung: Benutzer zur Docker-Gruppe hinzufügen:

sudo usermod -aG docker $USER
# Danach neu einloggen

Oder mit sudo ausführen:

sudo ./build_windows_on_linux.sh

Docker in Container-Umgebung (Docker-in-Docker)

Problem: Docker kann nicht in unprivilegierten Containern laufen.

Lösungen:

Wine-Alternative verwenden:
```
./build_windows_wine.sh
```
Auf Host-System bauen
GitHub Actions nutzen (siehe .github/workflows/)
Container mit --privileged starten (nicht empfohlen für Produktion)

WSL2 unter Windows

Problem: Docker-Befehle schlagen in WSL2 fehl.

Lösung:

Docker Desktop für Windows installieren
In Docker Desktop: Settings → Resources → WSL Integration aktivieren
WSL-Distribution auswählen

Docker-Image Download schlägt fehl

Symptom: Error pulling image oder Timeout

Lösungen:

Internetverbindung prüfen

Proxy konfigurieren:

export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

Manueller Download:

sudo docker pull cdrx/pyinstaller-windows:python3

Vergleich der Build-Methoden

Methode	Plattform	Vorteile	Nachteile
`build_windows.bat`	Windows	Nativ, zuverlässig	Braucht Windows
`build_windows_on_linux.sh`	Linux + Docker	Cross-compilation	Docker erforderlich
`build_windows_wine.sh`	Linux + Wine	Kein Docker nötig	Weniger zuverlässig
GitHub Actions	Cloud	Automatisiert	Braucht GitHub-Repo

Empfehlung: Für zuverlässige Windows-Builds verwenden Sie:

Native Windows (build_windows.bat) - Am zuverlässigsten
Docker auf Linux (build_windows_on_linux.sh) - Gut für CI/CD
GitHub Actions - Automatisiert bei jedem Push/Release

14 KiB Raw Blame History

PointCab Renamer - Deployment-Anleitung

Build-Status (Testergebnisse 2026-01-16)

Übersicht

Voraussetzungen

Benötigte Software

Installation der Voraussetzungen

Windows

Ubuntu

Windows-Build (.exe)

Automatisch (empfohlen)

Manuell

PyInstaller-Optionen erklärt

Bekannte Probleme unter Windows

Ubuntu-Build (Binary)

Automatisch (empfohlen)

Manuell

Bekannte Probleme unter Ubuntu

Cross-Compilation: Windows .exe unter Linux erstellen

Methode 1: Docker (Empfohlen)

Voraussetzungen

Verwendung

Was das Skript macht

Vorteile der Docker-Methode

Troubleshooting Docker

Methode 2: Wine (Fallback)

Voraussetzungen

Verwendung

Einschränkungen der Wine-Methode

Methode 3: GitHub Actions (Automatisiert)

Vergleich der Cross-Compilation-Methoden

Testen der Executables

Windows-Test

Ubuntu-Test

Checkliste für Tests

Distribution an Mitarbeiter

Bereitstellung

Empfohlene Ordnerstruktur für Mitarbeiter

Updates verteilen

Troubleshooting beim Build

"ModuleNotFoundError"

"Hidden import not found"

"Executable zu groß" (>100MB)

"tkinter funktioniert nicht"

Versionskontrolle

Troubleshooting: Docker-Probleme

Docker ist nicht installiert

Docker-Daemon startet nicht

Berechtigung verweigert

Docker in Container-Umgebung (Docker-in-Docker)

WSL2 unter Windows

Docker-Image Download schlägt fehl

Vergleich der Build-Methoden

14 KiB

Raw Blame History