📁 START-UT-DEV Framework 1.7 - TEMPLATES

Version: 1.7 Stand: 30.05.2026 Maintainer: darklithium dev@darklithium.de Validiert durch: referenz-app (metime-basiert) ✅

---

🎯 ZWECK

Dieses Verzeichnis enthält fertige Templates für Ubuntu Touch App-Entwicklung mit:

• QML (UI)
• Python (Backend via PyOtherSide)
• pure-qml-cmake (Builder)

Alle Templates sind validiert durch die erfolgreiche referenz-app-Implementierung.

---

📁 STRUKTUR

TEMPLATES/
├── README.md              # Diese Datei
├── CMakeLists.txt         # CMake-Konfiguration (Standard 1.7)
├── clickable.yaml         # Clickable-Konfiguration (Standard 1.7)
├── manifest.json.in       # App-Manifest Template
├── app.apparmor           # AppArmor-Profil Template
├── app.desktop.in         # Desktop-Datei Template
├── python_module_template.py  # Python-Modul Template
├── qml_main_template.qml  # QML Hauptdatei Template
└── .git/                  # Git-Hooks (Symlinks zu /DEV/git/hooks/)
    └── hooks/
        ├── pre-commit     # → /home/chrischi/DEV/git/hooks/pre-commit
        └── commit-msg     # → /home/chrischi/DEV/git/hooks/commit-msg

---

🚀 SCHNELLSTART: NEUE APP ERSTELLEN

1. Projektverzeichnis erstellen

mkdir -p /home/chrischi/DEV/UT/meine-app/{assets,qml,src}
cd /home/chrischi/DEV/UT/meine-app

2. Framework einbinden (Symlink)

ln -s /home/chrischi/DEV/tools/START-UT-DEV/1.7 START-UT-DEV

3. Templates kopieren & anpassen

# CMake & Clickable
cp START-UT-DEV/1.7/TEMPLATES/CMakeLists.txt .
cp START-UT-DEV/1.7/TEMPLATES/clickable.yaml .

# Manifest & Desktop
cp START-UT-DEV/1.7/TEMPLATES/manifest.json.in .
cp START-UT-DEV/1.7/TEMPLATES/app.apparmor meine-app.apparmor
cp START-UT-DEV/1.7/TEMPLATES/app.desktop.in meine-app.desktop.in

# Python & QML
cp START-UT-DEV/1.7/TEMPLATES/python_module_template.py src/meine-app.py
cp START-UT-DEV/1.7/TEMPLATES/qml_main_template.qml qml/Main.qml

# Assets (Beispiel-Icon)
cp START-UT-DEV/1.7/TEMPLATES/../ASSETS/logo.svg assets/

4. Platzhalter ersetzen

In allen Dateien <app-name> durch meine-app ersetzen:

# Schnell-Ersetzung (Vorsicht: prüfe alle Dateien manuell!)
find . -type f -exec sed -i 's/<app-name>/meine-app/g' {} \;
sed -i 's/<App-Name>/Meine App/g' meine-app.desktop.in manifest.json.in

5. Git einrichten (narrensicher)

# Git initialisieren
git init

# Hooks installieren (Symlinks!)
mkdir -p .git/hooks
cp -s /home/chrischi/DEV/git/hooks/pre-commit .git/hooks/
cp -s /home/chrischi/DEV/git/hooks/commit-msg .git/hooks/
chmod +x .git/hooks/*

# git-helper kopieren
cp /home/chrischi/DEV/git/git-helper.sh .
chmod +x git-helper.sh

6. Erstes Commit

./git-helper.sh commit 'feat: initiale Projektstruktur'

7. Build & Test

# Desktop-Test
qmlscene qml/Main.qml

# Clickable Build (für alle Architekturen)
clickable build --arch all

# Installation in QEMU
clickable install

---

📝 TEMPLATES IM DETAIL

📄 CMakeLists.txt

Zweck: Build-Konfiguration für pure-qml-cmake

Wichtige Punkte (1.7):

• CMAKE_AUTOMOC ON (für Qt5)
• Architektur-Triplet via dpkg-architecture
• PROJECT_NAME und FULL_PROJECT_NAME anpassen
• DATA_DIR / (Root für Click-Container)

Anpassungen:

• <app-name> durch deinen App-Namen ersetzen

---

📄 clickable.yaml

Zweck: Clickable Build-Konfiguration

Standard 1.7:

clickable_minimum_required: 8.8.0
builder: pure-qml-cmake
kill: qmlscene

Für Apps mit nativem Code:

• builder: cmake oder builder: qmake
• kill: <app-name>

---

📄 manifest.json.in

Zweck: App-Manifest für Click-Pakete

Wichtige Felder (1.7):

• name: <app-name>.darklithium (Format: appname.maintainer)
• maintainer: "Vorname Nachname <email>" (OHNE spitze Klammern um den Namen!)
• architecture: "all" (für pure-qml-cmake)
• framework: "ubuntu-sdk-20.04"

⚠️ WICHTIG: Nur Standardfelder verwenden! Keine permissions, policy_groups, read_path, write_path (schlagen Validierung fehl).

---

📄 app.apparmor

Zweck: AppArmor-Sicherheitsprofil

Standard 1.7:

{
    "policy_version": 20.04,
    "policy_groups": ["networking"]
}

Verfügbare Policy-Gruppen:

• networking (HTTP, etc.)
• content_exchange_source (Dateiaustausch)
• video (Video-Wiedergabe)
• pulseaudio (Audio)
• bluetooth (Bluetooth)
• location (Standort)
• contacts (Kontakte)
• calendar (Kalender)
• camera (Kamera)
• sensors (Sensoren)

---

📄 app.desktop.in

Zweck: Desktop-Datei für Lomiri

Wichtige Einträge (1.7):

• Exec=qmlscene %U qml/Main.qml (für pure-QML-Apps)
• X-Lomiri-Touch=true (für Ubuntu Touch)
• Icon=assets/logo.svg (Standard)
• X-Ubuntu-Applications=<app-name> (ohne .desktop Endung)

---

🐍 python_module_template.py

Zweck: Python-Backend für PyOtherSide

Wichtige Punkte (1.7):

• KEINE dbus-Importe (PyOtherSide-Kompatibilität)
• KEINE Top-Level print() Statements
• KEINE Top-Level Code-Ausführung
• Plattform-Erkennung via platform.machine()
• Ein Modul reicht für 90% der Apps

Beispiel-Funktionen:

• get_platform() → "arm64" oder "amd64"
• get_status_text() → Status für UI
• on_button_click() → Button-Handler
• get_data_dir() → Persistentes Datenverzeichnis

---

🎨 qml_main_template.qml

Zweck: QML-Hauptdatei

Wichtige Punkte (1.7):

• Imports:

  import QtQuick 2.7
  import QtQuick.Layouts 1.3  // NEU 1.7!
  import Lomiri.Components 1.3
  import Lomiri.Components.Popups 1.3
  import io.thp.pyotherside 1.4
  

• fontSize: Immer als STRING ("large", "x-large", "medium") - nicht units.sp()
• Layouts: QtQuick.Layouts 1.3 für ColumnLayout, RowLayout
• PyOtherSide: Qt.resolvedUrl("../src") FUNKTIONIERT!
• Button-Größen: 20x8 GU (200x80 DP) für Touch-Optimierung
• PageFooter: Existent NICHT in Lomiri.Components 1.3 → als Label implementieren

---

🔗 GIT-HOOKS (SYMLINKS)

Die Hooks in .git/hooks/ sind Symlinks zu /home/chrischi/DEV/git/hooks/:

.git/hooks/
├── pre-commit  → /home/chrischi/DEV/git/hooks/pre-commit
└── commit-msg  → /home/chrischi/DEV/git/hooks/commit-msg

Vorteile von Symlinks:

1. Zentrale Updates: Änderungen an den Hooks in /DEV/git/hooks/ gelten sofort für alle Projekte
2. Konsistenz: Alle Projekte nutzen dieselben Hooks
3. Wartung: Nur eine Stelle zu pflegen

Hooks im Detail:

pre-commit

Prüft vor jedem Commit:

• ✅ Branch-Naming (nur stable/testing/feature/bugfix/hotfix/release)
• ✅ Dateigrößen (max. 1MB)
• ✅ Sensible Daten (Passwörter, Keys, Tokens)
• ✅ Code-Style (kein Trailing Whitespace, LF Line Endings)

commit-msg

Prüft Commit-Messages:

• ✅ Subject-Länge (max. 72 Zeichen)
• ✅ Format: <typ>: <beschreibung>
• ✅ Typen: feat/fix/docs/style/refactor/test/chore/revert/perf/build/ci/WIP
• ✅ Beschreibung muss vorhanden sein

---

📊 PROJEKTSTRUKTUR (STANDARD 1.7)

meine-app/
├── CMakeLists.txt          # Build-Konfiguration
├── clickable.yaml          # Clickable-Konfiguration
├── manifest.json.in        # App-Manifest
├── meine-app.apparmor      # AppArmor-Profil
├── meine-app.desktop.in    # Desktop-Datei
├── .git/                   # Git-Repository
│   └── hooks/              # Git-Hooks (Symlinks)
│       ├── pre-commit
│       └── commit-msg
├── START-UT-DEV/           # Framework (Symlink)
│   └── 1.7/
│       ├── TEMPLATES/      # Templates
│       └── TOOLS/          # Tools (git-helper.sh)
├── assets/                 # Icons, Bilder
│   └── logo.svg           # App-Icon
├── qml/                    # QML-Dateien
│   └── Main.qml            # Haupteinstiegspunkt
└── src/                    # Python-Module
    └── meine-app.py        # Python-Backend

---

🧪 TESTING

Desktop-Test (schnell)

qmlscene qml/Main.qml

Clickable Build & Test

# Build für alle Architekturen
clickable build --arch all

# Installation in QEMU
clickable install

# Log prüfen
clickable log

Git Workflow Test

# Feature-Branch erstellen
./git-helper.sh new-feature test-funktion

# Änderungen machen...

# Commit (wird durch Hooks validiert)
./git-helper.sh commit 'feat: Testfunktion hinzugefügt'

# Push
./git-helper.sh push

---

📚 BEST PRACTICES (1.7)

✅ DO:

• Ein Python-Modul für einfache Apps (modulare Trennung ist optional)
• Qt.resolvedUrl("../src") für PyOtherSide-Imports
• fontSize als STRING verwenden
• Button-Größen: 20x8 GU für Touch
• Git-Hooks nutzen (verhindern Fehler)
• git-helper.sh nutzen (einfache Befehle)

❌ DON'T:

• dbus-Importe in Python-Modulen (PyOtherSide-Kompatibilität)
• Absolute Pfade für PyOtherSide-Imports
• Top-Level Code in Python-Modulen (wird nicht ausgeführt)
• units.sp() für fontSize (String-Werte bevorzugen)
• Direkte Commits auf stable (nur über Merge)

---

🔄 UPDATES

Templates aktualisieren

Die Templates in /DEV/tools/START-UT-DEV/1.7/TEMPLATES/ werden laufend verbessert.

Aktualisierung für bestehendes Projekt:

# CMakeLists.txt
cp /home/chrischi/DEV/tools/START-UT-DEV/1.7/TEMPLATES/CMakeLists.txt .

# clickable.yaml
cp /home/chrischi/DEV/tools/START-UT-DEV/1.7/TEMPLATES/clickable.yaml .

# Python-Template (neue Funktionen)
cp /home/chrischi/DEV/tools/START-UT-DEV/1.7/TEMPLATES/python_module_template.py src/meine-app.py

Hooks aktualisieren

Da die Hooks Symlinks sind, werden sie automatisch aktualisiert, wenn die zentraler Hooks in /DEV/git/hooks/ geändert werden.

---

📞 UNTERSTÜTZUNG

Häufige Probleme

Problem	Lösung
PyOtherSide-Modul wird nicht geladen	Qt.resolvedUrl("../src") verwenden
Button zu klein	20x8 GU (200x80 DP) verwenden
fontSize funktioniert nicht	String-Werte ("large") verwenden
Git-Hook blockiert Commit	git commit --no-verify (nur für Ausnahmen!)
PageFooter nicht verfügbar	Als Label implementieren

Referenz-App

• Pfad: /home/chrischi/DEV/UT/referenz-app/
• Status: ✅ ERFOLGREICH UMGESETZT
• Dokumentation: IMPLEMENTATION.md

Manifest

• Pfad: /home/chrischi/DEV/manifest.holy/manifest.holy
• Aktueller Stand: Python/QML-Standards 1.7

---

Letzte Aktualisierung: 30.05.2026 Version: 1.7 Maintainer: darklithium dev@darklithium.de