Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link
- pointer handlers declared directly on a window get no events, so put them on an Item inside it;
- Qt 6.12's `QtQuick/Color` shadows Omarchy's `Commons.Color`, so import `qs.Commons as Commons`.
- **pacman.conf order on aarch64:** `[omamobile]`, then `[omarchy]`, then Arch Linux ARM's repositories, so our Mesa and Omarchy's builds win. Use `omarchy update`, not `pacman -Syu`: on the phone it hands over to `omamobile-update` (patch 0012), which refuses a wrong order, low battery, another kernel or a bootloader package (`linux-omamobile` passes only when `omamobile-boot-update preflight` does), skips Snapper, the AUR and gum prompts, and holds boot-related migrations ([RELEASES](docs/RELEASES.md) §5.4).
- **Omarchy upgrades overwrite our Omarchy patches;** `omamobile-omarchy`'s pacman hook puts them back (all or nothing, from Omarchy's own files). Edit the series in `packages/omamobile-omarchy/patches` (`patches/omarchy` links there), bump that package's version, and make every patch apply with `--fuzz=0` on the Omarchy the phone runs: `packages/omamobile-omarchy/test/all` applies it to the real aarch64 package. A patch Omarchy has absorbed is reported as upstream: drop it.
- **Omarchy upgrades overwrite our Omarchy patches;** `omamobile-omarchy`'s pacman hook puts them back (all or nothing, from Omarchy's own files). Two families are selected by the installed Omarchy version: today's 4.0.6 phones use `packages/omamobile-omarchy/legacy-4.0.6/`; 4.5 uses `packages/omamobile-omarchy/patches/` (`patches/omarchy` links only to that family). Fixes for today's phones go in `legacy-4.0.6/`, and in `patches/` too when applicable to 4.5. Bump the package version and make the selected family apply with `--fuzz=0` on the Omarchy the phone runs: `packages/omamobile-omarchy/test/all` applies it to the real aarch64 package. A patch Omarchy has absorbed is reported as upstream: drop it.
- **`environment.d` can't unset a variable:** `VAR=` with an empty value is a syntax error, and the generator skips the line silently, so the old value stays. Set an explicit value instead (`omamobile-shell` uses `none`).
- **GeoClue answers no client until an authorization agent is registered for the caller's user,** and queues the call with no timeout, so every client just times out. `omamobile-gnss` runs GeoClue's demo agent as a user unit; app allow-list entries skip only the agent's question, not the agent.
- **Firewall changes** (ufw is on): arm `systemd-run --on-active=90 /usr/bin/ufw disable` first, then check with a fresh SSH connection (`tools/phone-ssh --fresh`).
Expand All @@ -232,7 +232,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link
| `kernel/configs/omamobile.config` | Config fragment on top of arm64 `defconfig`, commented by plan |
| `packages/omamobile-device-cheetah` | Boot-success marker, Wi-Fi and AoC start scripts, udev, modprobe and systemd policy |
| `packages/omamobile-shell`, `-sensors`, `-gnss`, `-audio`, `-remote` (opt-in, with `wlrctl`), `-fingerprint`, `-modem` (chroot profile), `libfprint`, `neard`, `mesa`, `hyprland`, `omamobile-keyring` | Userspace packages |
| `packages/omamobile-omarchy/patches/` (`patches/omarchy/` links there) | Omarchy changes waiting to land upstream, re-applied after every Omarchy upgrade |
| `packages/omamobile-omarchy/{legacy-4.0.6,patches}/` | Version-selected Omarchy families: current 4.0.6 phone fixes belong in `legacy-4.0.6/`, and also in the 4.5 `patches/` family when applicable; `patches/omarchy/` links only to 4.5 |
| `docs/DEVICES.md` | Supported-devices matrix |
| `~/omamobile-kernel/linux`, `wt-*`, `out-*` | The kernel clone, its worktrees and build outputs (outside the repo; `~/android/mainline` on older setups) |
| `~/android/reference/` | Stock captures and partition backups: private, never committed |
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ The kernel and boot images come from `bin/omamobile kernel`, `modules`, `initram
| `tools/build-packages`, `tools/build-rootfs`, `tools/install-phone`, `tools/phone-provision`, `tools/make-bundle` | The installer: aarch64 packages and the root image built on the laptop, the narrow fastboot installer, per-phone provisioning, release bundles (`rootfs/` holds the image's package lists; `tests/` their tests) |
| `tools/` | Staged bring-up and capture tools, on-phone probes, firmware extraction from the user's factory image, package and repository helpers |
| `packages/` | pacman packages: `omamobile-shell` (the phone profile for Omarchy's shell), `omamobile-apps` (the mobile apps desktop Omarchy lacks: Camera, Maps, NFC), `omacam` (the camera app, built from its own repository), `omamobile-device-cheetah` (Pixel 7 Pro support), `omamobile-device-felix` (Pixel Fold), `omamobile-sensors` (sensors and auto-rotate through the AoC), `omamobile-gnss` (location on demand), `omamobile-mirror` (the phone's screen and input on a computer over USB, VNC), `omamobile-remote` and a click-patched `wlrctl` (use the phone over ssh from a script or an agent; opt-in, [docs/REMOTE-TESTING.md](docs/REMOTE-TESTING.md)), `omamobile-audio` (PipeWire and speaker protection), `omamobile-speaker-tuning` (stock's speaker tuning, off by default), `omamobile-fingerprint` with a patched `libfprint`, `omamobile-modem` (the modem's vendor chroot profile), `omamobile-modem-sit` (the SIT client daemon; talks to the modem, registration untested), `omamobile-mmd` (ModemManager's D-Bus API in front of it, for GNOME Calls, Chatty and NetworkManager), `neard`, `omamobile-keyring` (the `[omamobile]` repository's signing key), patched `mesa` and `hyprland`. `tools/phone-install-package` builds one on the phone and installs it |
| `patches/omarchy/` | Changes to Omarchy for touch devices, to send upstream (`bridge-*` ones are stopgaps for the phone's older Omarchy); a link to `packages/omamobile-omarchy/patches`, whose pacman hook re-applies them after every Omarchy upgrade |
| `patches/omarchy/` | Changes to Omarchy for touch devices, to send upstream (`bridge-*` stopgaps are retained only in the legacy 4.0.6 family); a link to the 4.5 family in `packages/omamobile-omarchy/patches/`. The installed Omarchy version selects the family: today's 4.0.6 phones use `legacy-4.0.6/`, so fixes go there and also in `patches/` when applicable to 4.5; the pacman hook re-applies the selected family after upgrades |
| `bin/lineage-ref` | Builds LineageOS for the phone. Used as a rooted reference Android (M0) and, later, for Waydroid images |
| `kernel/configs/` | Our kernel config fragment, merged on top of arm64 `defconfig` |
| `device/cheetah/` | Pixel 7 Pro bring-up notes, one plan per subsystem, overlays, the initramfs and the device descriptor (`device.conf`) |
Expand Down
6 changes: 3 additions & 3 deletions docs/RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ The same Alpine-based initramfs, with release differences:

`omamobile-omarchy` (in every image built from 2026-10-13 on, and a dependency of `omamobile-shell`, so `omarchy update` brings it to older phones) owns both halves; the details are in the headers of its `bin/omamobile-update` and `bin/omamobile-omarchy-patches`.

**The patches survive upgrades.** The series lives in `packages/omamobile-omarchy/patches` (`patches/omarchy` links there) and ships in the package. Its pacman hook (`95-omamobile-omarchy-patches.hook`, PostTransaction on `omarchy`, `omarchy-dev` and itself) re-applies it after every transaction that replaces Omarchy's files, and `rootfs/build-inside` runs the same tool, so image builds and upgrades take one code path. Every run starts from Omarchy's own files (checked against the package's mtree), applies the series in a scratch tree with `--fuzz=0`, verifies it by reversing it back to Omarchy's files, and only then swaps the files in. A patch whose reverse applies is already in Omarchy (a backport that landed): it is skipped and reported, and should be dropped from the series. Any other failure leaves Omarchy's files exactly as shipped, logs to `/var/log/omamobile/omarchy-patches.log` and notifies the user (the lock's PIN pad may be missing until a fixed series ships). A file that matches neither Omarchy's copy nor the last patched one was changed by something else and is never overwritten.
**The patches survive upgrades.** Two series families ship in the package, selected by the installed Omarchy version: `packages/omamobile-omarchy/legacy-4.0.6/` for today's 4.0.6 phones, and `packages/omamobile-omarchy/patches/` for 4.5 (`patches/omarchy` links only to the latter). Fixes for today's phones must go in `legacy-4.0.6/`, and also in `patches/` when applicable to 4.5. Its pacman hook (`95-omamobile-omarchy-patches.hook`, PostTransaction on `omarchy`, `omarchy-dev` and itself) re-applies it after every transaction that replaces Omarchy's files, and `rootfs/build-inside` runs the same tool, so image builds and upgrades take one code path. Every run starts from Omarchy's own files (checked against the package's mtree), applies the series in a scratch tree with `--fuzz=0`, verifies it by reversing it back to Omarchy's files, and only then swaps the files in. A patch whose reverse applies is already in Omarchy (a backport that landed): it is skipped and reported, and should be dropped from the series. Any other failure leaves Omarchy's files exactly as shipped, logs to `/var/log/omamobile/omarchy-patches.log` and notifies the user (the lock's PIN pad may be missing until a fixed series ships). A file that matches neither Omarchy's copy nor the last patched one was changed by something else and is never overwritten.

**The update takes the phone's path.** Patch 0012 hands `omarchy update` to `omamobile-update`, which runs Omarchy's own `omarchy-update -y` unchanged, with stand-ins first on `PATH` for the steps that don't belong on a phone. Step by step:

Expand All @@ -232,7 +232,7 @@ The same Alpine-based initramfs, with release differences:

**The phone follows Omarchy's stable channel.** Phones installed before 2026-10-20 take `[omarchy]` from edge, which then carried 4.5.0rc1, a release candidate the phone's patches don't apply to. Switch before the next update, because the update would fetch the candidate in the same transaction as the fixed patches: `sudo sed -i 's|pkgs.omarchy.org/edge/|pkgs.omarchy.org/stable/|' /etc/pacman.conf && sudo rm -f /var/lib/pacman/sync/omarchy.db* /tmp/checkup-db-*/sync/omarchy.db*`. Removing edge's cached database matters: it is newer than stable's, so pacman's refresh keeps it and still offers the candidate. `omamobile-omarchy` 0.1.3's `omamobile-update` refuses an edge or rc `[omarchy]` and prints that line. Don't use Omarchy's own `omarchy-channel-set` or `omarchy-refresh-pacman` on the phone: they copy Omarchy's x86 `pacman.conf` and mirrorlist over the phone's (no `[omamobile]`, no Arch Linux ARM) and then upgrade everything.

**`[omamobile]` can hold Omarchy at a version the patches support.** `rootfs/packages.pinned` lists upstream package files by SHA-256 and URL (upstream's first, then our published copy, for when upstream prunes it); `tools/build-packages` adds them to `out/repo` unchanged, signed with the release key, so the daily publish carries them too; it refuses a pin with the name of a package we build, and `tools/release`'s packages stage refuses an index without every pin. `[omamobile]` comes first, so its copy wins over the newer one in `[omarchy]`: `omarchy update` (and `checkupdates`, behind the update toast) offers no newer Omarchy, and images install the pinned one. Since 2026-11-06 it holds `omarchy` and `omarchy-settings` at 4.0.6, because the series doesn't apply to 4.5 and 4.5's migrations install packages that replace ours (#433, #434). When a series for the new Omarchy ships, its line comes out and phones move on at their next update. A phone that already took the newer Omarchy keeps it: pacman doesn't downgrade on `-Syu`.
**`[omamobile]` can hold Omarchy at a version the patches support.** `rootfs/packages.pinned` lists upstream package files by SHA-256 and URL (upstream's first, then our published copy, for when upstream prunes it); `tools/build-packages` adds them to `out/repo` unchanged, signed with the release key, so the daily publish carries them too; it refuses a pin with the name of a package we build, and `tools/release`'s packages stage refuses an index without every pin. `[omamobile]` comes first, so its copy wins over the newer one in `[omarchy]`: `omarchy update` (and `checkupdates`, behind the update toast) offers no newer Omarchy, and images install the pinned one. Since 2026-11-06 it holds `omarchy` and `omarchy-settings` at 4.0.6, while the 4.5 companion changes and update validation remain pending (#433, #434); 4.5's migrations can install packages that replace ours. Once the new series and its companions are accepted, the maintainer moves the pins to the reviewed package versions and phones move on at their next update. A phone that already took the newer Omarchy keeps it: pacman doesn't downgrade on `-Syu`.

**Recovering a phone that took Omarchy 4.0.6 with `omamobile-omarchy` 0.1.0.** Its migration 1791403252 ran: `[omarchy]` sits above `[omamobile]`, Omarchy's Hyprland replaced the phone's, and no phone patch applies (no PIN pad on the lock screen, `omarchy update` no longer handed over). `omamobile-update` then refuses on the repository order, so the fix goes in by hand, over SSH or in a terminal on the phone:

Expand Down Expand Up @@ -281,7 +281,7 @@ For a first install, or to recover a phone that won't boot. One bundle per devic
| Piece | Where | Notes |
| --- | --- | --- |
| aarch64 packages without a phone | `tools/build-packages` | makepkg in an Arch Linux ARM container (the official tarball, MD5 and signature checked against the pinned build key, `tools/lib/alarm.sh`) under the laptop's qemu-user; signs with `keys/` into `out/repo/aarch64`. Mesa, Hyprland and libcamera take hours this way, so they're built only when named, once per version |
| The device's root image | `tools/build-rootfs`, `rootfs/` | pacstrap in that container: `rootfs/packages.base`, then Omarchy's own `install/omarchy-base.packages` (minus `rootfs/packages.omarchy-skip` and what isn't built for aarch64), then `rootfs/packages.omamobile`, the device package and the board's `ROOTFS_PACKAGES`, the `[omamobile]` repository itself, the kernel modules of the current build, and `patches/omarchy`. Output `out/omamobile-rootfs-<codename>-<date>-aarch64.img.zst`, `.sha256` and a `MANIFEST` with every package version (also inside, `/usr/share/omamobile/rootfs/MANIFEST`) |
| The device's root image | `tools/build-rootfs`, `rootfs/` | pacstrap in that container: `rootfs/packages.base`, then Omarchy's own `install/omarchy-base.packages` (minus `rootfs/packages.omarchy-skip` and what isn't built for aarch64), then `rootfs/packages.omamobile`, the device package and the board's `ROOTFS_PACKAGES`, the `[omamobile]` repository itself, the kernel modules of the current build, and `omamobile-omarchy`'s version-selected patch family. Output `out/omamobile-rootfs-<codename>-<date>-aarch64.img.zst`, `.sha256` and a `MANIFEST` with every package version (also inside, `/usr/share/omamobile/rootfs/MANIFEST`) |
| First boot | `packages/omamobile-firstboot` | reads `/etc/omamobile/firstboot.conf` (data, never sourced), creates the user, SSH keys, ufw with SSH on `usb0`, runs Omarchy's own setup leaves (skipping four that don't fit a phone), SDDM autologin and the lock, Omarchy's and our user setup, then deletes the file |
| Growing the root | `initramfs/init` (`grow_root`) | `resize2fs` before mounting, only for a file system labelled `omamobile-root` smaller than its partition; `omamobile.noresize` skips it |
| The installer | `tools/install-phone` (the bundle's `install`) | as described below, steps 1, 3-5; the factory-image step (2) is `tools/phone-provision` after the first boot instead |
Expand Down
20 changes: 20 additions & 0 deletions packages/omamobile-omarchy/LICENSE.omarchy
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
Copyright (c) David Heinemeier Hansson

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.
27 changes: 23 additions & 4 deletions packages/omamobile-omarchy/bin/omamobile-omarchy-patches
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,10 @@
omamobile-omarchy-patches verify [--root DIR]
omamobile-omarchy-patches restore [--root DIR] Omarchy's own files back

The series (/usr/share/omamobile/omarchy/patches, *.patch in name order) is
written against Omarchy's source tree. Every run starts again from Omarchy's
own files, never from the patched ones:
The installed Omarchy version selects the series under
/usr/share/omamobile/omarchy: legacy-4.0.6/ for 4.0.6, patches/ for 4.5.
Each family applies *.patch in name order against Omarchy's source tree.
Every run starts again from Omarchy's own files, never from the patched ones:

1. Pristine files. For each file the series touches (and each file an
earlier run touched), Omarchy's version as shipped: the file on disk if
Expand Down Expand Up @@ -500,6 +501,21 @@ def reverse_recover(root, rels, owned, series_dirs, work, log):
return {}


def default_series(root, packages):
"""Only the two independently qualified source families have a series.

Keep 4.0.6 available while preparing an upgrade; never apply 4.5 contexts
to the currently running old package. Explicit --series remains the
offline prospective rehearsal interface.
"""
families = {v.rsplit("-", 1)[0] for _n, v, _p in packages}
if families == {"4.0.6"}:
return os.path.join(root, "usr/share/omamobile/omarchy/legacy-4.0.6")
if families == {"4.5.0"}:
return os.path.join(root, SERIES)
raise Failure("Omarchy version has no qualified mobile patch series; refusing")


def apply(root, series_dir, log, hook=False):
state_dir = os.path.join(root, STATE_DIR)
os.makedirs(state_dir, exist_ok=True)
Expand All @@ -517,6 +533,9 @@ def apply(root, series_dir, log, hook=False):
status["omarchy"] = " ".join("%s %s" % (n, v) for n, v, _ in packages)
previous = load_json(os.path.join(state_dir, "state.json")) or {}
try:
if series_dir is None:
series_dir = default_series(root, packages)
status["series"] = "/" + os.path.relpath(series_dir, root)
patches, series_hash = load_series(series_dir, root)
except Failure as e:
return fail(root, status, e, log, hook)
Expand Down Expand Up @@ -805,7 +824,7 @@ def main(argv):
if cmd == "apply":
log = Log(root, quiet)
try:
return apply(root, series or os.path.join(root, SERIES), log, hook)
return apply(root, series, log, hook)
except Failure as e:
return fail(root, {"time": now(), "log": "/" + LOG, "applied": [], "upstream": [], "omarchy": None}, e, log, hook)
if cmd == "restore":
Expand Down
4 changes: 4 additions & 0 deletions packages/omamobile-omarchy/install
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,8 @@ for f in patches/*.patch; do
done
install -Dm644 libalpm/95-omamobile-omarchy-patches.hook "$d/usr/share/libalpm/hooks/95-omamobile-omarchy-patches.hook"
install -Dm644 LICENSE "$d/usr/share/licenses/omamobile-omarchy/LICENSE"
install -Dm644 LICENSE.omarchy "$d/usr/share/licenses/omamobile-omarchy/omarchy-MIT"
install -Dm644 version "$d/usr/share/omamobile/omarchy/version"
for f in legacy-4.0.6/*.patch; do
install -Dm644 "$f" "$d/usr/share/omamobile/omarchy/legacy-4.0.6/${f##*/}"
done
Loading