builauncher 0.1.1__tar.gz

builauncher-0.1.1/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.3
+Name: builauncher
+Version: 0.1.1
+Summary: Pie-menu launcher with type-to-search, on BUI
+Requires-Dist: blenderui>=0.4.1
+Requires-Dist: numpy
+Requires-Dist: rapidfuzz>=3
+Requires-Dist: jeepney>=0.8 ; sys_platform == 'linux'
+Requires-Dist: pyside6>=6.6
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# builauncher
+
+A pie-menu launcher drawn with [BUI](https://github.com/ppmpreetham/BUI), Blender's UI as a
+library, in a Qt window through PySide6 (Qt for Python; PyQt is not used). Press a hotkey,
+flick towards an item, or type to search every command and installed app.
+
+![The pie, and a search for "p"](assets/screenshot.png)
+
+## Install
+
+    uv tool install builauncher   # or: pipx install builauncher, or uvx builauncher to try it
+    builauncher install           # start the daemon at every login
+    builauncher daemon &          # start it now, for this session
+
+Then press Ctrl+Alt+Space. `builauncher uninstall` removes the login entries. Run `install`
+from an installed copy, not from `uvx`: the environment `uvx` makes is temporary.
+
+## Use
+
+| Input | Result |
+| --- | --- |
+| Hotkey | Open the pie. The hotkey again closes it. |
+| Hold the hotkey, move the pointer, release | Run the item in that direction. |
+| Drag from the empty middle | Run the item in the drag direction. |
+| Click an item | Run it, or open its sub-pie. |
+| Click the pie centre | Back to the parent pie. |
+| Search item, or start typing | Search menu commands and installed apps. |
+| Up, Down, Return | Pick a result and run it. |
+| Backspace on an empty search, or Tab | Back to the pie. |
+| Escape, Alt+F4, a click outside | Close. |
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `builauncher` or `builauncher open` | Open the menu. With no daemon running, it opens once and exits. |
+| `builauncher daemon` | Stay running and bind the global shortcut. |
+| `builauncher stop` | Stop the running daemon. |
+| `builauncher install` | Add the login entry and the app entry (XDG autostart). |
+| `builauncher uninstall` | Remove them. |
+
+`open` and `daemon` take `--config FILE`.
+
+## Config
+
+Copy `builauncher/default.toml` to `~/.config/builauncher/menu.toml` and edit it. On Windows,
+copy `builauncher/default-windows.toml` to `%APPDATA%\builauncher\menu.toml`.
+
+    shortcut = "CTRL+ALT+space"   # asked for at the first start
+    scale = 1.0                   # size of the pie and the search
+    apps = true                   # also search installed apps
+
+    [[item]]
+    name = "Terminal"
+    icon = "CONSOLE"              # a Blender icon name
+    exec = "konsole"              # run a command
+
+    [[item]]
+    name = "Media"
+    icon = "SOUND"
+    pie = "media"                 # open the sub-pie named media
+
+    [[pie.media]]
+    name = "Next"
+    icon = "FF"
+    exec = "playerctl next"
+
+An item has either `exec` or `pie`. Each `[[pie.NAME]]` table is one item of that
+sub-pie, and its items can open further sub-pies. `pie = "places"` is built in: Home,
+Documents, Downloads, Music, Pictures, Videos and the Trash. A `[[pie.places]]` of your
+own replaces it.
+
+The top pie holds 7 items, because Search takes one slot. A sub-pie also holds 7,
+because Back takes one. A pie that opens itself, directly or through another, is rejected
+at load.
+
+## Desktop support
+### Linux
+The daemon asks the desktop for its shortcut through the
+[XDG GlobalShortcuts portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.GlobalShortcuts.html),
+which KDE Plasma, GNOME 48 and later, and Hyprland provide. After the first start, change
+the shortcut in the desktop's shortcut settings. On a desktop without the portal, bind the
+`builauncher` command to a key yourself.
+
+The menu opens under the pointer. On Wayland an app cannot place its window or read the
+pointer, so builauncher covers the screen with a transparent window and draws the menu
+where the pointer enters it. That window is a layer-shell overlay when Qt has the
+layer-shell plugin, and a full-screen window otherwise, so it works on any compositor,
+GNOME included. On X11 the window moves to the pointer.
+
+`install` writes an XDG autostart entry. Sway and Hyprland do not run those, so add
+`builauncher daemon` to their startup config.
+
+### Windows
+
+The commands and the config are the same. Underneath:
+
+| Linux | Windows |
+| --- | --- |
+| Shortcut from the XDG portal | `RegisterHotKey`; a timer polls `GetAsyncKeyState` for the release, so hold and release still works. If another app holds the shortcut, the daemon says so. |
+| `install` writes an XDG autostart entry | `install` adds a value under `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` that starts the daemon with `pythonw`, so no console opens. |
+| Unix socket in `$XDG_RUNTIME_DIR` | Named pipe `\\.\pipe\builauncher` |
+| Apps from `.desktop` files | Apps from Start Menu shortcuts |
+| `xdg-open`, `trash:///` | `explorer`, `shell:RecycleBinFolder` |
+| Transparent full-screen window, menu under the pointer | Frameless, always-on-top window at the pointer |
+
+The Windows default menu uses Windows Terminal (`wt`), sends the media keys through
+PowerShell, and locks, sleeps, restarts and shuts down with `rundll32` and `shutdown`.
+Sleep hibernates instead when hibernation is on.
+
+## Development
+
+    uv venv --system-site-packages
+    uv sync
+    uv run pytest
+    uv build
+
+## Thanks
+
+- [Blender](https://www.blender.org), whose UI and pie menus BUI follows.
+- [BUI](https://github.com/ppmpreetham/BUI), which draws the menu.
+- [Kando](https://github.com/kando-menu/kando), for the gestures, timings and fades.
+- [PySide6](https://doc.qt.io/qtforpython-6/) (Qt for Python), for the window.
+- [RapidFuzz](https://github.com/rapidfuzz/RapidFuzz), for the search.
+- [jeepney](https://gitlab.com/takluyver/jeepney), for D-Bus.
+- [numpy](https://numpy.org), for the transparency.

builauncher-0.1.1/README.md

@@ -0,0 +1,126 @@
+# builauncher
+
+A pie-menu launcher drawn with [BUI](https://github.com/ppmpreetham/BUI), Blender's UI as a
+library, in a Qt window through PySide6 (Qt for Python; PyQt is not used). Press a hotkey,
+flick towards an item, or type to search every command and installed app.
+
+![The pie, and a search for "p"](assets/screenshot.png)
+
+## Install
+
+    uv tool install builauncher   # or: pipx install builauncher, or uvx builauncher to try it
+    builauncher install           # start the daemon at every login
+    builauncher daemon &          # start it now, for this session
+
+Then press Ctrl+Alt+Space. `builauncher uninstall` removes the login entries. Run `install`
+from an installed copy, not from `uvx`: the environment `uvx` makes is temporary.
+
+## Use
+
+| Input | Result |
+| --- | --- |
+| Hotkey | Open the pie. The hotkey again closes it. |
+| Hold the hotkey, move the pointer, release | Run the item in that direction. |
+| Drag from the empty middle | Run the item in the drag direction. |
+| Click an item | Run it, or open its sub-pie. |
+| Click the pie centre | Back to the parent pie. |
+| Search item, or start typing | Search menu commands and installed apps. |
+| Up, Down, Return | Pick a result and run it. |
+| Backspace on an empty search, or Tab | Back to the pie. |
+| Escape, Alt+F4, a click outside | Close. |
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `builauncher` or `builauncher open` | Open the menu. With no daemon running, it opens once and exits. |
+| `builauncher daemon` | Stay running and bind the global shortcut. |
+| `builauncher stop` | Stop the running daemon. |
+| `builauncher install` | Add the login entry and the app entry (XDG autostart). |
+| `builauncher uninstall` | Remove them. |
+
+`open` and `daemon` take `--config FILE`.
+
+## Config
+
+Copy `builauncher/default.toml` to `~/.config/builauncher/menu.toml` and edit it. On Windows,
+copy `builauncher/default-windows.toml` to `%APPDATA%\builauncher\menu.toml`.
+
+    shortcut = "CTRL+ALT+space"   # asked for at the first start
+    scale = 1.0                   # size of the pie and the search
+    apps = true                   # also search installed apps
+
+    [[item]]
+    name = "Terminal"
+    icon = "CONSOLE"              # a Blender icon name
+    exec = "konsole"              # run a command
+
+    [[item]]
+    name = "Media"
+    icon = "SOUND"
+    pie = "media"                 # open the sub-pie named media
+
+    [[pie.media]]
+    name = "Next"
+    icon = "FF"
+    exec = "playerctl next"
+
+An item has either `exec` or `pie`. Each `[[pie.NAME]]` table is one item of that
+sub-pie, and its items can open further sub-pies. `pie = "places"` is built in: Home,
+Documents, Downloads, Music, Pictures, Videos and the Trash. A `[[pie.places]]` of your
+own replaces it.
+
+The top pie holds 7 items, because Search takes one slot. A sub-pie also holds 7,
+because Back takes one. A pie that opens itself, directly or through another, is rejected
+at load.
+
+## Desktop support
+### Linux
+The daemon asks the desktop for its shortcut through the
+[XDG GlobalShortcuts portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.GlobalShortcuts.html),
+which KDE Plasma, GNOME 48 and later, and Hyprland provide. After the first start, change
+the shortcut in the desktop's shortcut settings. On a desktop without the portal, bind the
+`builauncher` command to a key yourself.
+
+The menu opens under the pointer. On Wayland an app cannot place its window or read the
+pointer, so builauncher covers the screen with a transparent window and draws the menu
+where the pointer enters it. That window is a layer-shell overlay when Qt has the
+layer-shell plugin, and a full-screen window otherwise, so it works on any compositor,
+GNOME included. On X11 the window moves to the pointer.
+
+`install` writes an XDG autostart entry. Sway and Hyprland do not run those, so add
+`builauncher daemon` to their startup config.
+
+### Windows
+
+The commands and the config are the same. Underneath:
+
+| Linux | Windows |
+| --- | --- |
+| Shortcut from the XDG portal | `RegisterHotKey`; a timer polls `GetAsyncKeyState` for the release, so hold and release still works. If another app holds the shortcut, the daemon says so. |
+| `install` writes an XDG autostart entry | `install` adds a value under `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` that starts the daemon with `pythonw`, so no console opens. |
+| Unix socket in `$XDG_RUNTIME_DIR` | Named pipe `\\.\pipe\builauncher` |
+| Apps from `.desktop` files | Apps from Start Menu shortcuts |
+| `xdg-open`, `trash:///` | `explorer`, `shell:RecycleBinFolder` |
+| Transparent full-screen window, menu under the pointer | Frameless, always-on-top window at the pointer |
+
+The Windows default menu uses Windows Terminal (`wt`), sends the media keys through
+PowerShell, and locks, sleeps, restarts and shuts down with `rundll32` and `shutdown`.
+Sleep hibernates instead when hibernation is on.
+
+## Development
+
+    uv venv --system-site-packages
+    uv sync
+    uv run pytest
+    uv build
+
+## Thanks
+
+- [Blender](https://www.blender.org), whose UI and pie menus BUI follows.
+- [BUI](https://github.com/ppmpreetham/BUI), which draws the menu.
+- [Kando](https://github.com/kando-menu/kando), for the gestures, timings and fades.
+- [PySide6](https://doc.qt.io/qtforpython-6/) (Qt for Python), for the window.
+- [RapidFuzz](https://github.com/rapidfuzz/RapidFuzz), for the search.
+- [jeepney](https://gitlab.com/takluyver/jeepney), for D-Bus.
+- [numpy](https://numpy.org), for the transparency.

builauncher-0.1.1/builauncher/__main__.py

@@ -0,0 +1,49 @@
+"""The `builauncher` command. Qt loads only in the process that shows the menu."""
+import argparse
+import os
+import subprocess
+import sys
+
+from .install import install, uninstall
+from .system import WINDOWS
+from .trigger import STOP, TRIGGER, send
+
+
+def parser() -> argparse.ArgumentParser:
+    cli = argparse.ArgumentParser(prog="builauncher", description="Pie-menu launcher on BUI.")
+    sub = cli.add_subparsers(dest="command", metavar="command")
+    sub.add_parser("open", help="open the menu: trigger the daemon, or open it once (the default)")
+    sub.add_parser("daemon", help="stay running, bind the global shortcut, wait for triggers")
+    sub.add_parser("stop", help="stop the running daemon")
+    sub.add_parser("install", help="add the autostart entry and the app entry")
+    sub.add_parser("uninstall", help="remove them")
+    for name in ("open", "daemon"):
+        sub.choices[name].add_argument("--config", metavar="TOML", help="menu file (default: ~/.config/builauncher/menu.toml)")
+    return cli
+
+
+def main() -> int:
+    args = parser().parse_args()
+    match args.command:
+        case "install":
+            install()
+        case "uninstall":
+            uninstall()
+        case "stop":
+            if not send(STOP):
+                print("builauncher: no daemon runs", file=sys.stderr)
+                return 1
+        case "daemon" | "open" | None:
+            daemon = args.command == "daemon"
+            if not daemon and send(TRIGGER):
+                return 0
+            config = [args.config] if getattr(args, "config", None) else []
+            argv = [sys.executable, "-m", "builauncher.app", *(["--daemon"] if daemon else []), *config]
+            if WINDOWS:  # Windows execv does not quote arguments with spaces
+                return subprocess.call(argv)
+            os.execv(sys.executable, argv)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

builauncher-0.1.1/builauncher/app.py

@@ -0,0 +1,48 @@
+"""The launcher process: `--daemon` waits for triggers, else it opens the menu once."""
+import os
+import sys
+from pathlib import Path
+
+import buipy
+from PySide6.QtWidgets import QApplication
+
+from .items.apps import apps
+from .config import load
+from .daemon import serve
+from .launcher import Launcher
+from .items.menu import actions
+from .shortcut import bind
+from .window import Overlay, layer_shell
+
+SHELL_VAR = "QT_WAYLAND_SHELL_INTEGRATION"
+
+
+def main() -> int:
+    daemon = "--daemon" in sys.argv[1:]
+    paths = [Path(a) for a in sys.argv[1:] if a != "--daemon"]
+    # wayland: a layer surface has no frame, no tiling, and stays above windows
+    shell = os.environ.get(SHELL_VAR)
+    if layer_shell():
+        os.environ[SHELL_VAR] = "layer-shell"
+    qt = QApplication(sys.argv[:1])
+    qt.setQuitOnLastWindowClosed(not daemon)
+    cfg = load(paths[0] if paths else None)
+    buipy.kit_set_scale(cfg.scale)  # before any size is taken from the kit unit
+    entries = [*actions(cfg.menu), *(("App", a) for a in (apps() if cfg.apps else ()))]
+    launcher = Launcher(cfg.menu, entries, lambda: window.dismiss())
+    window = Overlay(launcher, daemon)
+    # the window has its shell now; launched apps must not inherit layer-shell (they open full screen)
+    os.environ.pop(SHELL_VAR, None) if shell is None else os.environ.update({SHELL_VAR: shell})
+    if not daemon:
+        window.summon()
+        return qt.exec()
+    server = serve(window.trigger)  # noqa: F841 (kept alive)
+    try:
+        portal = bind(cfg.shortcut, window.trigger, window.release)  # noqa: F841 (kept alive)
+    except (OSError, ValueError) as error:
+        print(f"builauncher: no global shortcut ({error}); bind `builauncher` in the desktop", file=sys.stderr)
+    return qt.exec()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

builauncher-0.1.1/builauncher/config.py

@@ -0,0 +1,37 @@
+"""Load the menu from ~/.config/builauncher/menu.toml (or the bundled default)."""
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from .items.menu import PIE_SLOTS, Menu, parse
+from .items.places import places
+from .system import WINDOWS, config_dir
+
+DEFAULT = Path(__file__).with_name("default-windows.toml" if WINDOWS else "default.toml")
+SHORTCUT = "CTRL+ALT+space"  # XDG shortcuts format
+SCALE = 1.0  # BUI ui scale; 1 is Blender's default
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    menu: Menu
+    apps: bool = True
+    shortcut: str = SHORTCUT  # asked for at the first bind; then the desktop's settings own it
+    scale: float = SCALE
+
+
+def user_path() -> Path:
+    return config_dir() / "menu.toml"
+
+
+def load(path: Path | None = None) -> Config:
+    path = path or (user_path() if user_path().exists() else DEFAULT)
+    raw = tomllib.loads(path.read_text())
+    pies = {"places": places(), **raw.get("pie", {})}  # built-in pies; a [[pie.places]] replaces one
+    items = tuple(parse(item, pies) for item in raw.get("item", []))
+    if not 0 < len(items) < PIE_SLOTS:
+        raise ValueError(f"{path}: the top menu needs 1 to {PIE_SLOTS - 1} items (one slot is Search)")
+    scale = float(raw.get("scale", SCALE))
+    if not 0.5 <= scale <= 4:
+        raise ValueError(f"{path}: scale must be 0.5 to 4")
+    return Config(Menu("builauncher", items), raw.get("apps", True), raw.get("shortcut", SHORTCUT), scale)

builauncher-0.1.1/builauncher/daemon.py

@@ -0,0 +1,31 @@
+"""One running launcher: listen on a Unix socket (a named pipe on Windows) for triggers and stop."""
+from collections.abc import Callable
+
+from PySide6.QtCore import QCoreApplication
+from PySide6.QtNetwork import QLocalServer
+
+from .system import server_name
+from .trigger import STOP, TRIGGER
+
+
+def serve(on_trigger: Callable[[], None]) -> QLocalServer:
+    """Listen for triggers. Keep the result alive."""
+    path = server_name()
+    QLocalServer.removeServer(path)  # a socket left by a crash
+    server = QLocalServer()
+    if not server.listen(path):
+        raise OSError(f"{path}: {server.errorString()}")
+
+    handlers = {TRIGGER: on_trigger, STOP: QCoreApplication.quit}
+
+    def read(message: bytes) -> None:
+        if handler := handlers.get(message):
+            handler()
+
+    def accept() -> None:
+        while conn := server.nextPendingConnection():
+            conn.readyRead.connect(lambda c=conn: read(c.readAll().data()))
+            conn.disconnected.connect(conn.deleteLater)
+
+    server.newConnection.connect(accept)
+    return server

builauncher-0.1.1/builauncher/default-windows.toml

@@ -0,0 +1,75 @@
+# Copy to %APPDATA%\builauncher\menu.toml and edit.
+# The same format as the Linux default.toml: an item runs a command (`exec`) or opens a
+# sub-pie (`pie = "name"`); `pie = "places"` is built in. `icon` is a Blender icon name.
+apps = true  # also search Start Menu shortcuts
+shortcut = "CTRL+ALT+space"  # RegisterHotKey; another app may already hold it
+scale = 1.0  # size of the pie and the search (BUI ui scale)
+
+# the top pie: 1 to 7 items, as Search takes a slot
+
+[[item]]
+name = "Terminal"
+icon = "CONSOLE"
+exec = "wt"
+
+[[item]]
+name = "Browser"
+icon = "WORLD"
+exec = 'explorer "https://"'
+
+[[item]]
+name = "Files"
+icon = "FILE_FOLDER"
+pie = "places"
+
+[[item]]
+name = "Media"
+icon = "SOUND"
+pie = "media"
+
+[[item]]
+name = "System"
+icon = "PREFERENCES"
+pie = "system"
+
+# sub-pies. Windows has no media command, so WScript sends the media keys (179, 176, 177).
+
+[[pie.media]]
+name = "Play / Pause"
+icon = "PLAY"
+exec = 'powershell -NoProfile -WindowStyle Hidden -Command "(New-Object -ComObject WScript.Shell).SendKeys([char]179)"'
+
+[[pie.media]]
+name = "Next"
+icon = "FF"
+exec = 'powershell -NoProfile -WindowStyle Hidden -Command "(New-Object -ComObject WScript.Shell).SendKeys([char]176)"'
+
+[[pie.media]]
+name = "Previous"
+icon = "REW"
+exec = 'powershell -NoProfile -WindowStyle Hidden -Command "(New-Object -ComObject WScript.Shell).SendKeys([char]177)"'
+
+[[pie.system]]
+name = "Lock"
+icon = "LOCKED"
+exec = "rundll32.exe user32.dll,LockWorkStation"
+
+[[pie.system]]
+name = "Sleep"
+icon = "SORTTIME"
+exec = "rundll32.exe powrprof.dll,SetSuspendState 0,1,0"  # hibernates if hibernation is on
+
+[[pie.system]]
+name = "Power"
+icon = "QUIT"
+pie = "power"
+
+[[pie.power]]
+name = "Restart"
+icon = "FILE_REFRESH"
+exec = "shutdown /r /t 0"
+
+[[pie.power]]
+name = "Shut down"
+icon = "QUIT"
+exec = "shutdown /s /t 0"

builauncher-0.1.1/builauncher/default.toml

@@ -0,0 +1,79 @@
+# Copy to ~/.config/builauncher/menu.toml and edit.
+# An item runs a command (`exec`) or opens a sub-pie (`pie = "name"`).
+# `[[pie.name]]` tables are that sub-pie's items: 1 to 7, as Back takes a slot.
+# `pie = "places"` is built in: home, documents, downloads, ... and the trash.
+# `icon` is a Blender icon name (CONSOLE, FILE_FOLDER, PLAY, ...).
+apps = true  # also search installed .desktop apps
+# global shortcut, asked of the desktop at the first daemon start (XDG GlobalShortcuts portal).
+# after that, change it in the desktop's shortcut settings.
+shortcut = "CTRL+ALT+space"
+scale = 1.0  # size of the pie and the search (BUI ui scale)
+
+# the top pie: 1 to 7 items, as Search takes a slot
+
+[[item]]
+name = "Terminal"
+icon = "CONSOLE"
+exec = "konsole"
+
+[[item]]
+name = "Browser"
+icon = "WORLD"
+exec = "xdg-open https://"
+
+[[item]]
+name = "Files"
+icon = "FILE_FOLDER"
+pie = "places"
+
+[[item]]
+name = "Media"
+icon = "SOUND"
+pie = "media"
+
+[[item]]
+name = "System"
+icon = "PREFERENCES"
+pie = "system"
+
+# sub-pies
+
+[[pie.media]]
+name = "Play / Pause"
+icon = "PLAY"
+exec = "playerctl play-pause"
+
+[[pie.media]]
+name = "Next"
+icon = "FF"
+exec = "playerctl next"
+
+[[pie.media]]
+name = "Previous"
+icon = "REW"
+exec = "playerctl previous"
+
+[[pie.system]]
+name = "Lock"
+icon = "LOCKED"
+exec = "loginctl lock-session"
+
+[[pie.system]]
+name = "Suspend"
+icon = "SORTTIME"
+exec = "systemctl suspend"
+
+[[pie.system]]
+name = "Power"
+icon = "QUIT"
+pie = "power"
+
+[[pie.power]]
+name = "Reboot"
+icon = "FILE_REFRESH"
+exec = "systemctl reboot"
+
+[[pie.power]]
+name = "Shut down"
+icon = "QUIT"
+exec = "systemctl poweroff"

builauncher-0.1.1/builauncher/fuzzy.py

@@ -0,0 +1,13 @@
+"""Fuzzy search with RapidFuzz."""
+from collections.abc import Callable, Sequence
+
+from rapidfuzz import fuzz, process, utils
+
+CUTOFF = 50  # lowest WRatio score (0-100) that shows
+
+
+def search[T](query: str, items: Sequence[T], key: Callable[[T], str], limit: int = 8) -> list[T]:
+    """Return the best `limit` items for query, best first."""
+    found = process.extract(query, [key(i) for i in items], scorer=fuzz.WRatio,
+                            processor=utils.default_process, limit=limit, score_cutoff=CUTOFF)
+    return [items[index] for _, _, index in found]

builauncher-0.1.1/builauncher/install.py

@@ -0,0 +1,82 @@
+"""`builauncher install`: start the daemon at login.
+
+Linux: an XDG autostart entry, and the .desktop file the shortcut portal knows the app by.
+Both are freedesktop.org standards, so KDE, GNOME, Xfce, Cinnamon and others read them.
+Windows: a value under the user's Run registry key, with pythonw so no console opens.
+"""
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .system import APP_ID, WINDOWS
+
+if WINDOWS:
+    import winreg
+
+RUN_KEY = r"Software\Microsoft\Windows\CurrentVersion\Run"
+ENTRY = """[Desktop Entry]
+Type=Application
+Name=builauncher
+Comment=Pie menu launcher
+Exec={exec}
+Icon=system-run
+Terminal=false
+NoDisplay=true
+X-GNOME-Autostart-enabled=true
+"""
+
+
+def paths() -> tuple[Path, Path]:
+    """The app entry (portal app id) and the autostart entry."""
+    data = Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local/share")
+    config = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return data / "applications" / f"{APP_ID}.desktop", config / "autostart" / f"{APP_ID}.desktop"
+
+
+def command() -> str:
+    """The installed `builauncher` script, else this Python with -m."""
+    return shutil.which("builauncher") or f"{sys.executable} -m builauncher"
+
+
+def install() -> None:
+    install_windows() if WINDOWS else install_xdg()
+
+
+def uninstall() -> None:
+    uninstall_windows() if WINDOWS else uninstall_xdg()
+
+
+def install_windows() -> None:
+    pythonw = Path(sys.executable).with_name("pythonw.exe")
+    with winreg.OpenKey(winreg.HKEY_CURRENT_USER, RUN_KEY, 0, winreg.KEY_SET_VALUE) as key:
+        winreg.SetValueEx(key, APP_ID, 0, winreg.REG_SZ, f'"{pythonw}" -m builauncher daemon')
+    print(f"added {APP_ID} to HKCU\\{RUN_KEY}")
+    print("start it now with: builauncher daemon   (it starts by itself at the next sign-in)")
+
+
+def uninstall_windows() -> None:
+    with winreg.OpenKey(winreg.HKEY_CURRENT_USER, RUN_KEY, 0, winreg.KEY_SET_VALUE) as key:
+        try:
+            winreg.DeleteValue(key, APP_ID)
+        except FileNotFoundError:
+            pass  # not installed
+    print(f"removed {APP_ID} from HKCU\\{RUN_KEY}")
+
+
+def install_xdg() -> None:
+    app, autostart = paths()
+    for path, args in ((app, ""), (autostart, " daemon")):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(ENTRY.format(exec=command() + args))
+        print(f"wrote {path}")
+    if tool := shutil.which("update-desktop-database"):
+        subprocess.run([tool, str(app.parent)], check=False)
+    print("start it now with: builauncher daemon &   (it starts by itself at the next login)")
+
+
+def uninstall_xdg() -> None:
+    for path in paths():
+        path.unlink(missing_ok=True)
+        print(f"removed {path}")