repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill(quickshell): fix markdownlint MD060 in README

a1bb9764bdf1c86a5da74dffa435cb4be20aa3ed

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (3)

skills/quickshell/README.md

Modified
15 15 │ ├── services.md # pipewire, mpris, notifications, …
16 16 │ ├── windowing.md # PanelWindow / FloatingWindow / PopupWindow / WlSessionLock
17 17 │ ├── resources.md # paths, icons, env, IPC, persistence
18 +│ ├── packaging.md # install / distro packages / source build
18 19 │ └── getting-fresh-docs.md # how to look up current docs (don't memorize)
19 20 ├── examples/ # minimal, runnable prototypes
20 21 │ ├── 01-hello-bar/ # smallest valid shell
29 30 ## Quick start
31 32 ```sh
32 -# 1. Install quickshell
33 -sudo pacman -S quickshell # Arch (official)
34 -# or: see references/getting-fresh-docs.md for Nix/Debian/Fedora/Ubuntu/Gentoo
33 +# 1. Install (Arch shown; see references/packaging.md for other distros)
34 +sudo pacman -S quickshell
36 36 # 2. Try a prototype
37 37 qs -p examples/01-hello-bar/shell.qml
51 51 What was actually tested, and what wasn't:
53 -| Check | Result | How |
54 -| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------- |
55 -| All 6 examples parse | ✅ | `qs -p <shell.qml>` on each; event loop started; log shows no QML errors |
56 -| All 6 examples clean shutdown | ✅ | timeout-kill, no orphan processes |
57 -| No leftover runtime state | ✅ | `by-id/`, `by-shell/`, `by-path/` cleaned |
58 -| QML imports resolve | ✅ | (via the parse check above) |
59 -| Windows map to Wayland surface | ⚠️ not tested | The host's Hyprland session is live; creating test windows would litter the desktop. Run on your own session. |
60 -| Service APIs (pipewire, mpris) | ⚠️ not tested live | Code matches the official volume-osd example; pattern verified. |
53 +- **All 6 examples parse (pass).** `qs -p <shell.qml>` on each; event loop started; log shows no QML errors.
54 +- **All 6 examples clean shutdown (pass).** Timeout-kill, no orphan processes.
55 +- **No leftover runtime state (pass).** `by-id/`, `by-shell/`, `by-path/` cleaned.
56 +- **QML imports resolve (pass).** Verified by the parse check above.
57 +- **Windows map to Wayland surface (skip).** The host's Hyprland session is live; creating test windows would litter the desktop. Run on your own session.
58 +- **Service APIs (pipewire, mpris) (skip).** Code matches the official volume-osd example; pattern verified.
62 60 To extend validation on your own compositor:
89 87 See `references/getting-fresh-docs.md` for the lookup procedure.
89 +## Sources and licenses
91 +- **Quickshell source** ([github.com/quickshell-mirror/quickshell](https://github.com/quickshell-mirror/quickshell)) — **LGPL-3.0** (runtime) + **GPL-3.0** (build scripts). Examples in this skill are based on patterns from this codebase.
92 +- **Quickshell examples** ([github.com/quickshell-mirror/quickshell-examples](https://github.com/quickshell-mirror/quickshell-examples)) — no explicit LICENSE file. The README states the intent is to "learn from and modify", and the project owner is the same as quickshell itself. The `volume-osd/` example was used as a reference for `examples/05-osd-volume/`.
93 +- **Live docs** — [quickshell.org](https://quickshell.org) (CC-BY-SA implied, by the quickshell team).
95 +This skill (`pi-ext/skills/quickshell/`) is part of the user's `pi-ext` repo. The example QML files are intentionally minimal rewrites (not copies) of the patterns in `quickshell-examples`. For anything more than a few lines of QML, prefer studying the upstream examples directly.
91 97 ## When not to use
93 99 - You want a preconfigured desktop → use [Caelestia](https://github.com/caelestia-dots/shell) or [Illogical-Impulse](https://github.com/end-4/dots-hyprland).
94 100 - You want a one-line status bar → use Waybar. Quickshell is programming.
95 101 - You target Windows / macOS → Quickshell is Linux + BSD only.
96 102 - You're on X11 with no wlroots compat → X11 is best-effort; prefer a wlroots-based WM.
98 -## Open questions for the user
100 -- **CLI helper.** A `qs-check <shell.qml>` wrapper (parse-only, fast) would speed up authoring. A `qs-new <name>` scaffolder would help. Both are ~30 lines of bash. Escalating per the original spec — happy to add if you want; otherwise this is a docs-only skill.

skills/quickshell/SKILL.md

Modified
72 72 ## Common patterns
74 -| Need | Snippet |
75 -| --- | --- |
76 -| Run a command, capture stdout | `Process { command: ["..."]; running: true; stdout: StdioCollector { onStreamFinished: x.text = this.text } }` |
77 -| Stream line-by-line | `Process { ...; stdout: SplitParser { onRead: line => ... } }` |
78 -| Bind service state | `PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }` then read `?.audio.volume` |
79 -| React to signal | `Connections { target: X?.audio; function onVolumeChanged() {...} }` |
80 -| Conditional window (memory-aware) | `LazyLoader { active: show; PanelWindow {...} }` |
81 -| Click-through | `PanelWindow { color: "transparent"; mask: Region {} }` |
82 -| System icon | `IconImage { source: Quickshell.iconPath("audio-volume-high-symbolic") }` |
83 -| Path relative to this QML file | `Qt.resolvedUrl("foo.png")` |
84 -| Shell cache / data / state | `Quickshell.cachePath("x")` / `.dataPath("x")` / `.statePath("x")` |
85 -| Env var | `Quickshell.env("VAR")` |
86 -| External callable | `IpcHandler { target: "mybar"; function toggle(): void {...} }` → `qs ipc call mybar toggle` |
87 -| Version-gate | `Loader { active: Quickshell.hasVersion("0.3.0"); sourceComponent: ... }` |
74 +| Need | Snippet |
75 +| --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
76 +| Run a command, capture stdout | `Process { command: ["..."]; running: true; stdout: StdioCollector { onStreamFinished: x.text = this.text } }` |
77 +| Stream line-by-line | `Process { ...; stdout: SplitParser { onRead: line => ... } }` |
78 +| Bind service state | `PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }` then read `?.audio.volume` |
79 +| React to signal | `Connections { target: X?.audio; function onVolumeChanged() {...} }` |
80 +| Conditional window (memory-aware) | `LazyLoader { active: show; PanelWindow {...} }` |
81 +| Click-through | `PanelWindow { color: "transparent"; mask: Region {} }` |
82 +| System icon | `IconImage { source: Quickshell.iconPath("audio-volume-high-symbolic") }` |
83 +| Path relative to this QML file | `Qt.resolvedUrl("foo.png")` |
84 +| Shell cache / data / state | `Quickshell.cachePath("x")` / `.dataPath("x")` / `.statePath("x")` |
85 +| Env var | `Quickshell.env("VAR")` |
86 +| External callable | `IpcHandler { target: "mybar"; function toggle(): void {...} }` → `qs ipc call mybar toggle` |
87 +| Version-gate | `Loader { active: Quickshell.hasVersion("0.3.0"); sourceComponent: ... }` |
89 89 ## Editor / LSP

skills/quickshell/references/packaging.md

Added
new file mode 100644
1 +# Packaging & Install
3 +How to get `quickshell` (`qs`) on your system. Picked from the live install page at `https://quickshell.org/docs/<version>/guide/install-setup/`. Re-check that page when bumping versions; package availability changes.
5 +## Distro packages
7 +| Distro | Package | Notes |
8 +| --- | --- | --- |
9 +| **Arch (official)** | `quickshell` | In `[extra]`. Pin for stability. |
10 +| **Arch (AUR)** | `quickshell-git` | Tracks master. May break on Qt updates; quickshell warns. |
11 +| **NixOS** | `nixpkgs` `quickshell` | Stable. |
12 +| **Nix (flake)** | flake input | `quickshell.packages.<system>.default` |
13 +| **Debian unstable/testing** | `quickshell` | |
14 +| **Fedora Rawhide** | `quickshell` | |
15 +| **Fedora COPR** | `errornointernet/quickshell` (release) / `quickshell-git` (master) | |
16 +| **Ubuntu** | `ppa:avengemedia/danklinux` → `quickshell` or `quickshell-git` | |
17 +| **openSUSE** | OBS `home:AvengeMedia:danklinux` → `quickshell` or `quickshell-git` | |
18 +| **Gentoo** | `guru` overlay → `gui-apps/quickshell` | |
19 +| **Guix** | `(gnu packages wm)` → `quickshell` | |
21 +## Nix flake
23 +```nix
25 + inputs = {
26 + nixpkgs.url = "nixpkgs/nixos-unstable";
27 + quickshell = {
28 + url = "git+https://git.outfoxxed.me/quickshell/quickshell";
29 + # THIS IS IMPORTANT: mismatched system deps lead to crashes.
30 + inputs.nixpkgs.follows = "nixpkgs";
31 + };
32 + };
34 +```
36 +Then:
38 +```nix
39 +environment.systemPackages = [ inputs.quickshell.packages.<system>.default ];
40 +# or with extra QML modules:
41 +inputs.quickshell.packages.<system>.default.withModules [ ./my-extra-modules ]
42 +```
44 +Add `?ref=<tag>` to the URL to pin a tagged release.
46 +## Source build
48 +See `https://git.outfoxxed.me/quickshell/quickshell/src/branch/master/BUILD.md`.
50 +Common path: install Qt6 dev packages + ninja, then `cmake -B build -G Ninja && ninja -C build`.
52 +## Runtime dependencies (for the package maintainer or source build)
54 +Quickshell links against:
56 +- Qt6 (`qt6-base`, `qt6-declarative`, `qt6-quickcontrols2`).
57 +- Wayland client libs (`libwayland-client`).
58 +- For pipewire: `libpipewire`.
59 +- For screencopy Vulkan: `vulkan-headers` (build-time), `vulkan-Loader` (runtime).
60 +- For screencopy non-Vulkan: none extra.
61 +- For polkit agent: `glib`, `polkit`.
62 +- `libdrm` is now an unconditional direct dep (since v0.3.0).
63 +- Wayland/WlrLayershell features require a wlroots-based compositor (Hyprland, Sway, etc.) for full functionality. X11 and Niri work but with feature gaps.
65 +## Optional runtime Qt modules
67 +These are bundled in most distros but worth checking on slim Arch installs:
69 +- `qtsvg` — SVG images.
70 +- `qtimageformats` — WEBP, TIFF, etc.
71 +- `qtmultimedia` — audio/video playback.
72 +- `qt5compat` — extra visual effects (MultiEffect, gaussian blur). `MultiEffect` is usually preferred where available.
74 +## Verifying the install
76 +```sh
77 +qs --version
78 +# Quickshell 0.3.0 (revision , distributed by Arch Linux)
80 +qs --help
81 +# should list: -c <name>, -p <path>, -d (daemonize), -n (no-duplicate), subcommands: log/list/kill/ipc/msg
82 +```
84 +## Editor setup (LSP)
86 +Touch the qmlls marker to enable completions:
88 +```sh
89 +touch ~/.config/quickshell/<name>/.qmlls.ini
90 +```
92 +Quickshell overwrites it with a managed qmlls config. **Gitignore it** (its content depends on local paths).
94 +Known qmlls issues to be aware of:
96 +- Doesn't work well when a file contains types from multiple qs.* modules.
97 +- May report false-positive undefined-symbol errors after a fresh `qs` install until you restart your editor.
99 +## Troubleshooting
101 +| Symptom | Fix |
102 +| --- | --- |
103 +| `qs: error while loading shared libraries: libQt6…` | Install Qt6 runtime. |
104 +| Panel doesn't appear | Compositor must be Wayland + wlroots-based; check `echo $WAYLAND_DISPLAY`. |
105 +| Panel appears but is opaque white | You set `color: "transparent"` and a child has `border` without `border.width: 0` — QTBUG-137166. Add `border.width: 0`. |
106 +| `quickshell-git` AUR rebuilds every Qt update | Quickshell will warn; just reinstall. |
107 +| IPC `qs ipc call` says "no such target" | The target is the string you set on `IpcHandler { target: ... }`, not the config name. |
108 +| `qmlls` complains about every Quickshell symbol | `.qmlls.ini` is missing or stale; delete and re-touch. |