alpymist

Decisions

How Alpymist works, and why

Alpymist writes its reasoning down. Each foundational choice is an architecture decision record: what forced the decision, what was chosen, and what it costs. They are the best introduction to the project there is.

Start here

Decisions

  1. ADR 0001 accepted One desktop, three renderers Two requirements pull in opposite directions:
  2. ADR 0002 accepted Everything is a signed package The most substantive technical criticism aimed at Omarchy-style projects is about delivery, not taste:
  3. ADR 0003 accepted Foundational choices Four decisions taken at project start. Recorded together because each was a genuine fork, and because the reasoning matters more than the outcome when we revisit them.
  4. ADR 0004 accepted Confining unsafe, and why our binaries are not static Two decisions forced by building the EGL probe. Both are consequences of the same thing: asking the graphics stack a question means talking to C.
  5. ADR 0005 accepted Alpine 3.24 as the base, and why stable is now enough Two constraints had to meet. DeniseUI 0.24 — the toolkit the splash and installer are built on — requires rustc 1.95. And ADR 0003 chose to base Alpymist on Alpine stable rather than edge.
  6. ADR 0006 accepted Upgrades come from the repository, on a stable or a dev channel Trying a change on a real machine meant building an ISO and installing it again. Installed systems already had everything an upgrade needs, a signed repository and apk upgrade. But packages were built only with a release, alongside the ISOs, and every change had to wait for a hand-signed publish behind a pkgrel bump.
  7. ADR 0007 accepted Settings: one command line, one library, one app Alpymist's settings are wherever they were first needed. The installer writes the keyboard layout, time zone and hostname once, and after that they are changed by hand with doas. Nothing sets the touchpad, the monitors or the language. Power and Wi-Fi have good popups under the bar, each with its own logic. The menu's appearance lives in the menu's own configuration file.
  8. ADR 0008 accepted One version for everything, and the run number as the build number Every first-party package carried pkgver=0.0.1 and a pkgrel of its own, bumped by hand whenever that package changed. Three releases later the repository said 0.0.1 and GitHub said v0.0.3, and the packages ranged from 0.0.1-r0 to 0.0.1-r15. Nothing in the version told you which release a package belonged to, and alpymist-about, which reads those versions off the installed system, could only report what it was given.
  9. ADR 0009 accepted The screensaver is a picture, and the lock is somewhere else Alpymist had no idle behaviour at all. No tier's configuration started swayidle, though the Wayland tiers installed it; nothing turned a screen off; nothing locked one. A laptop left alone on the login desk kept its backlight on until the battery was flat. Super+L ran swaylock, and that was the whole of it.
  10. ADR 0010 accepted The lock screen is the login screen Locking was swaylock -f -c 0b121e: a blue screen with a circle in the middle of it. Six things ran it — Super+L under Hyprland, W-l and the menu under labwc, the system menu's Lock, a lid set to lock, and the idle watch at the blank timeout and before sleeping — so it was the one part of Alpymist that everybody saw regularly and that looked like nothing else in it. It does not say whose session it is, what time it is, or that it is Alpymist at all.
  11. ADR 0011 accepted Secure by default; the unsafe is opt-in Alpine's own promise is "small, simple, secure", and Alpymist is built on it (ADR 0005). Until now that has been true of Alpymist one decision at a time, without being written down anywhere:
  12. ADR 0012 accepted Thunderbolt and USB4 devices are asked about, and the IOMMU is on A Thunderbolt or USB4 device is connected to the computer as if it were inside it. Its PCIe tunnel lets it, or anything behind it, read and write memory by DMA. So most firmware does not let such a device in by itself. It sets the host controller's security level to user or secure and leaves the decision to the operating system, which says yes by writing to the device's authorized file in sysfs.
  13. ADR 0013 accepted A keyring unlocked at login, and an SSH agent that forgets Nothing in an Alpymist session kept secrets. Programs that store a password or a token ask the Secret Service (org.freedesktop.secrets) for somewhere to put it, and there was none. What they do then differs, and none of it is good:
  14. ADR 0014 accepted Copy and paste on Super, and a history kept only when asked Copy and paste differ by window: a terminal takes Ctrl+Shift+C and Ctrl+Shift+V, since Ctrl+C interrupts and Ctrl+V quotes the next key, and everything else takes Ctrl+C and Ctrl+V. On Wayland, what was copied belongs to the window that copied it, so it is gone when that window closes, and nothing remembers what was copied before.
  15. ADR 0015 accepted Screens: a layout for each set of screens, applied through Hyprland Every screen was placed by one line in hyprland.conf, monitor = , preferred, auto, 1: left to right, in whatever order Hyprland found them. Nothing remembered a layout. A laptop moved between a dock at the desk, a projector and nothing at all came up however Hyprland happened to find its screens, and a closed lid on the dock left the built-in panel on behind it, with workspaces and windows on a screen nobody could see (#17).
  16. ADR 0016 accepted Fingerprints unlock the screen and answer prompts, never log in The X1 Carbon's reader, a Synaptics 06cb:009a, has no libfprint driver. validity-fprintd (our own, packaged since #77) drives it and serves fprintd's D-Bus interface in fprintd's place, and the Fingerprints window (#78) enrols fingers with it. Enrolled fingers did nothing yet: every PAM stack still asked for the password alone (#58).
  17. ADR 0017 accepted AI usage in the bar: providers as programs, keys in the keyring People who work with AI models pay for them in two ways that are both easy to run out of without noticing: a subscription with limits over a window of time, and an API key that spends money. The vendors show each on a web page of their own. #16 asks for one place: an icon in the bar beside Wi-Fi and the battery.
  18. ADR 0018 accepted Graphics in a virtual machine: a second Mesa, asked for Alpymist in a virtual machine was slow in a way Ubuntu in the same virtual machine was not. The reason is one word in a build recipe. QEMU and UTM offer a guest the host's graphics card through virtio-gpu, and the kernel takes the offer ([drm] features: +virgl), but the Mesa driver for it, virgl, is not in Alpine 3.24's Mesa: galliumdrivers in main/mesa leaves it out on every architecture. Mesa says virtiogpu: driver missing and falls back to llvmpipe, and Hyprland, which draws everything through GL ES shaders, then draws every frame on the processor.
  19. ADR 0019 accepted A watchdog for the session The bar on the X1 stopped following the workspaces: the numbers stayed as they were, the underline did not move, and a click on a number changed the screen and not the bar. Nothing had crashed. Each bar shows its screen's workspaces from what Hyprland says on its event socket; Hyprland takes a listener off that socket when it falls sixty-four events behind (EventManager.cpp, 0.54.3), and waybar 0.15.0, taken off, reads the end of the socket for ever and never connects again. Its development branch stops reading instead, which is no better. What held the bar up that long was not found — twenty-five configuration reloads in a row did not do it — but stopping the bar while events arrive does it every time.
  20. ADR 0020 accepted Hardware reports, sent by the person and not by the system Alpymist was installed on a 2009 MacBook Pro, and three things were wrong that no machine it had been tried on had shown: the Wi-Fi card was not found, the pointer was not drawn, and the image was not seen by the firmware at all. Finding out why meant asking the person at the machine to type lspci -nn, dmesg | grep firmware and the like, and to copy the answers back by hand, from a machine with no network.
  21. ADR 0021 accepted Firmware nobody may ship is fetched by the machine that asks Alpymist says it is for old machines. A 2009 MacBook Pro has a Broadcom BCM4322 Wi-Fi card, as every Mac of those years and a great many other laptops have one of its family. The kernel's b43 driver has it, and does nothing without firmware. That firmware is in no package of Alpine's, nor of any other distribution's, because Broadcom never gave anyone leave to pass it on. Debian, Arch and the rest ship a tool that downloads Broadcom's own driver for routers, which has the firmware in it, and cuts it out on the machine.
  22. ADR 0022 accepted The keyboard's control keys No volume, brightness, media or radio key did anything on any machine. Hyprland binds nothing by itself, and there is no desktop daemon underneath it to catch those keys: no elogind, no settings daemon. The kernel is built without RFKILLINPUT, so it leaves the radio keys to the session as well. The manual said to bind them by hand.
  23. ADR 0023 accepted What Alpymist's programs depend on At 0.3.4 Cargo.lock held 317 packages that are not ours, and the programs the packages ship linked 164 of them. All came from crates.io and none was chosen carelessly, but nothing said how one gets in: a dependency arrived as a line in a Cargo.toml, in a change about something else, and was reviewed as that something else.
  24. ADR 0024 accepted PAM bindings of our own, and a second crate with unsafe The lock screen checks the password, and a finger, through libpam. ADR 0010 weighed writing the conversation ourselves against a safe wrapper, and took the wrapper: nonstick, so that ADR 0004's rule held as written, with all of the project's unsafe in alpymist-glesprobe.
  25. ADR 0025 accepted A D-Bus client of our own Three things are spoken to over the system bus: iwd, the fingerprint daemon, and polkit. All three were spoken to with zbus, through its blocking API.
  26. ADR 0026 accepted Wayland without a toolkit Everything in the session that is not a terminal is put on screen by one of four hosts: the menu's, the popups', the application window's and the lock screen's. All four stood on smithay-client-toolkit, and through it on calloop, a cursor-theme loader, client-side decoration types and a second memory-map crate: eighteen packages that nothing else in what ships needed, under every desktop program there is. The four hosts were also four copies of the same plumbing — about a hundred and fifty lines each of handlers that did nothing, written out because the toolkit's traits asked for them.
  27. ADR 0027 accepted Development for glibc: a box of another distribution, documented and not shipped ADR 0003 answered software built for glibc with Flatpak, and rejected gcompat. That holds for applications. It does not hold as well for the tools of someone who writes software, and Zed is what showed it.
  28. ADR 0028 accepted A file manager: Thunar, with drives opened by hand Settings › Default applications said "Nothing installed" for folders, and a keyboard's Files key ran alpymist open files into nothing, or into whatever else had said it opens folders: on a machine with Visual Studio Code from the Store, an editor.
  29. ADR 0029 accepted What opens the rest: a viewer, a player, an archiver, and a terminal's programs Settings › Default applications said "Nothing installed" for pictures, films, music and archives. A picture double-clicked in the file manager of ADR 0028 opened in the browser, a zip in nothing.
  30. ADR 0030 accepted A game for a screen with no desktop, and for systems that are not ours Solitaire (ADR 0029's addenda) is a window on the desktop. Its rules, its table and the hand that plays it are a library with no window in it, and Denise draws to a display through DRM/KMS and reads a mouse and a keyboard from the kernel without a compositor: the login screen, the installer and the splash are made that way.