feat: initiale Projektstruktur nach Framework 1.7
This commit is contained in:
darklithium
@@ -0,0 +1,396 @@
|
||||
# 📁 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
|
||||
```bash
|
||||
mkdir -p /home/chrischi/DEV/UT/meine-app/{assets,qml,src}
|
||||
cd /home/chrischi/DEV/UT/meine-app
|
||||
```
|
||||
|
||||
### 2. Framework einbinden (Symlink)
|
||||
```bash
|
||||
ln -s /home/chrischi/DEV/tools/START-UT-DEV/1.7 START-UT-DEV
|
||||
```
|
||||
|
||||
### 3. Templates kopieren & anpassen
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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)
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
./git-helper.sh commit 'feat: initiale Projektstruktur'
|
||||
```
|
||||
|
||||
### 7. Build & Test
|
||||
```bash
|
||||
# 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:**
|
||||
```yaml
|
||||
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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```qml
|
||||
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)
|
||||
```bash
|
||||
qmlscene qml/Main.qml
|
||||
```
|
||||
|
||||
### Clickable Build & Test
|
||||
```bash
|
||||
# Build für alle Architekturen
|
||||
clickable build --arch all
|
||||
|
||||
# Installation in QEMU
|
||||
clickable install
|
||||
|
||||
# Log prüfen
|
||||
clickable log
|
||||
```
|
||||
|
||||
### Git Workflow Test
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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>
|
||||
Reference in New Issue
Block a user