diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ff14455 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,59 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +A development environment for building and customizing SDDM login themes for KDE Plasma 6. Themes are written in pure QtQuick/QML (no KDE Plasma library dependencies) and can be previewed in a standalone window without restarting SDDM. + +## Commands + +### Live preview (primary development loop) +```sh +./scripts/preview.sh # preview the default theme +./scripts/preview.sh -theme # preview a specific theme +qml6 preview/Preview.qml # one-shot preview (no file watching) +``` + +### Lint (static analysis + runtime type check) +```sh +./scripts/lint-qml.sh # lint all themes +./scripts/lint-qml.sh -theme # lint a specific theme +``` +CI runs this on every push/PR. It runs `qmllint` for static analysis, then launches the preview under `xvfb` for 3 seconds to catch runtime type errors (`Unable to assign`, `ReferenceError`, `TypeError`). + +### Full-fidelity SDDM test +```sh +./scripts/test-sddm.sh # test default theme with real SDDM greeter +./scripts/test-sddm.sh -theme +``` + +## Architecture + +### Theme structure +Themes live under `themes//`. The default theme is at `themes/default/`. + +Each theme contains: +- `Main.qml` — SDDM entry point; root `Item` that uses SDDM-injected context properties +- `theme.conf` — all configurable values (colors, fonts, background, clock format, screen dimensions) +- `metadata.desktop` — SDDM theme registration metadata +- `components/` — UI components (Clock, LoginForm, SessionSelector, PowerBar) +- `assets/` — background image and other static assets + +### Preview harness +`preview/Preview.qml` mirrors `Main.qml` layout but replaces SDDM context properties with mock objects (`mockSddm`, `mockConfig`, `mockUserModel`, `mockSessionModel`, `mockKeyboard`). The preview script symlinks the selected theme's `components/` and `assets/` into `preview/` so relative QML imports resolve correctly. + +In preview mode, use password `test` for successful login; any other password triggers "Login Failed". + +### SDDM context properties +SDDM injects five globals that themes depend on: `sddm`, `config`, `userModel`, `sessionModel`, `keyboard`. Components receive these as explicit properties rather than accessing globals directly, making them portable between Main.qml (real SDDM) and Preview.qml (mocks). + +### QML style +All scripts set `QT_QUICK_CONTROLS_STYLE=Basic` to avoid Breeze/Plasma-specific errors outside a full Plasma session. + +## Key Conventions + +- Pure QtQuick only — no `org.kde.plasma.*`, `org.kde.breeze.components`, or `Kirigami` imports +- Components take dependencies as explicit props (not SDDM context property access) +- `qmllint` warnings about unresolved SDDM globals are expected and tolerated; only actual errors fail CI +- All config values come through `theme.conf` and are accessed via `config.` in QML diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4d7da7d --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Derryl Carter + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index f3b013c..8eb0727 100644 --- a/README.md +++ b/README.md @@ -6,89 +6,49 @@ Build and customize your KDE login screen without having to actually reinstall t This project gives you a live-preview development environment for SDDM themes on KDE Plasma 6. Edit QML, tweak colors, swap backgrounds -- and see every change instantly in a standalone window. When you're happy with the result, install it as your real login screen with one command. -**Who is this for?** Anyone who wants to customize their KDE/SDDM login screen -- whether you're importing an existing theme to tweak it, or building one from scratch. - -## What's Inside - -``` -kde-lockscreen-builder/ -├── Main.qml # SDDM entry point (the actual theme) -├── metadata.desktop # Theme registration (Theme-API 2.0, Qt6) -├── theme.conf # All configurable values: colors, fonts, background, clock -├── components/ -│ ├── Clock.qml # Date/time display -│ ├── LoginForm.qml # Username + password fields, login button -│ ├── SessionSelector.qml # Desktop session dropdown -│ └── PowerBar.qml # Suspend / reboot / shutdown buttons -├── preview/ -│ └── Preview.qml # Mock harness — previews your theme without SDDM -├── scripts/ -│ ├── preview.sh # File-watcher: auto-restarts preview on every save -│ └── test-sddm.sh # Full-fidelity SDDM greeter test -├── assets/ -│ └── background.jpg # Your background image -└── faces/ - └── .face.icon # Default user avatar placeholder -``` +## Quick Start -## Prerequisites +### Prerequisites - KDE Plasma 6 with SDDM - Qt 6 (`qt6-declarative` package -- provides `qml6`) - `entr` for file-watching (`sudo pacman -S entr` on Arch) -## Quick Start +### Start from the included starter theme -### Option A: Start From the Included Starter Theme - -The repo ships with a minimal, clean theme that works out of the box. Clone and preview it immediately: +The repo ships with a minimal, clean theme that works out of the box: ```sh git clone https://github.com/derryl/kde-lockscreen-builder.git cd kde-lockscreen-builder -cp /path/to/your/wallpaper.jpg assets/background.jpg +cp /path/to/your/wallpaper.jpg themes/default/assets/background.jpg ./scripts/preview.sh ``` Edit any `.qml` file or `theme.conf`, save, and the preview window restarts automatically. -### Option B: Import an Existing Theme - -Already have a theme you want to modify? Copy its files into this project to get the live-preview workflow: - -1. Clone this repo: - - ```sh - git clone https://github.com/derryl/kde-lockscreen-builder.git - cd kde-lockscreen-builder - ``` - -2. Copy the theme's files over the project files. SDDM themes typically have a `Main.qml`, `metadata.desktop`, `theme.conf`, and asset directories -- replace the ones in this repo with yours: +### Or import an existing theme - ```sh - # Example: importing from an installed SDDM theme - cp -r /usr/share/sddm/themes/some-theme/* . - ``` +Already have a theme you want to modify? You can find community themes on the [KDE Store](https://store.kde.org/browse?cat=101&ord=rating), or copy one that's already installed on your system: -3. Launch the preview: - - ```sh - ./scripts/preview.sh - ``` +```sh +# Example: importing from an installed SDDM theme +cp -r /usr/share/sddm/themes/some-theme/* themes/default/ +./scripts/preview.sh +``` - If the imported theme uses KDE/Plasma-specific QML imports (e.g. `org.kde.plasma.*`), the standalone preview won't be able to render those parts. You can still use `./scripts/test-sddm.sh` for full-fidelity testing, or incrementally replace those imports with pure QtQuick equivalents. +If the imported theme uses KDE/Plasma-specific QML imports (e.g. `org.kde.plasma.*`), the standalone preview won't render those parts. You can still use `./scripts/test-sddm.sh` for full-fidelity testing, or incrementally replace those imports with pure QtQuick equivalents. ## Development Workflow -### Live Preview (primary loop) - -`preview/Preview.qml` mocks all SDDM-provided objects (`sddm`, `userModel`, `sessionModel`, `config`, `keyboard`) so your theme renders in a standalone window -- no real SDDM greeter needed. +### Live preview ```sh -./scripts/preview.sh +./scripts/preview.sh # preview the default theme +./scripts/preview.sh -theme # preview a specific theme under themes/ ``` -This watches all `.qml`, `.conf`, and image files using `entr`. On every save, the preview window is killed and relaunched automatically. +This watches all `.qml`, `.conf`, and image files. On every save, the preview window restarts automatically. In preview mode, type the password `test` to simulate a successful login. You can also launch the preview once without file-watching: @@ -96,9 +56,7 @@ You can also launch the preview once without file-watching: qml6 preview/Preview.qml ``` -In preview mode, type the password `test` to simulate a successful login. Any other password triggers the "Login Failed" notification. - -### Full-Fidelity SDDM Test +### Full-fidelity SDDM test Periodically verify your theme against the real SDDM greeter: @@ -140,7 +98,7 @@ Changes to `theme.conf` are picked up by the file watcher just like QML changes. ## Installing Your Theme -When you're satisfied with your theme, install it so SDDM uses it at your real login screen. SDDM themes live in `/usr/share/sddm/themes/`. +SDDM themes live in `/usr/share/sddm/themes/`. ### 1. Choose a theme name @@ -155,19 +113,17 @@ Theme-Id=my-login-theme **Symlink (recommended during development)** -- lets you keep editing and see changes on next login: ```sh -sudo ln -sf "$(pwd)" /usr/share/sddm/themes/my-login-theme +sudo ln -sf "$(pwd)/themes/default" /usr/share/sddm/themes/my-login-theme ``` **Copy (for a final install):** ```sh -sudo cp -r . /usr/share/sddm/themes/my-login-theme +sudo cp -r themes/default /usr/share/sddm/themes/my-login-theme ``` ### 3. Activate the theme -Tell SDDM to use your theme: - ```sh sudo mkdir -p /etc/sddm.conf.d sudo tee /etc/sddm.conf.d/theme.conf > /dev/null < Colors & Themes > Login Screen (SDDM)**. ### 4. Verify -Run the full-fidelity test against the installed path to confirm everything works: - ```sh sddm-greeter-qt6 --test-mode --theme /usr/share/sddm/themes/my-login-theme ``` -## Architecture Notes - -The included starter theme is built with **pure QtQuick** -- no imports from `org.kde.plasma.*`, `org.kde.breeze.components`, or `Kirigami`. This means: - -- Total control over every visual element -- No dependency on KDE Plasma libraries at the SDDM level -- Easy mocking: only 5 SDDM globals need stubs (`sddm`, `config`, `userModel`, `sessionModel`, `keyboard`) +## Useful Links -Components receive their dependencies as explicit properties rather than relying on SDDM context properties directly, making them testable in the preview harness and reusable across themes. +- [SDDM Theming Guide](https://github.com/sddm/sddm/wiki/Theming) -- API reference for the SDDM context properties (`sddm`, `userModel`, `sessionModel`, etc.) and theme structure +- [KDE Store: SDDM Login Themes](https://store.kde.org/browse?cat=101&ord=rating) -- community-made themes to use as starting points or inspiration +- [Qt QML Documentation](https://doc.qt.io/qt-6/qtqml-index.html) -- language reference for QML +- [Qt Quick Documentation](https://doc.qt.io/qt-6/qtquick-index.html) -- the UI framework used by SDDM themes ## License