first commit

2026-11-04 09:43:05 -07:00
commit c33736775b
25 changed files with 2056 additions and 0 deletions
@@ -0,0 +1,91 @@
+# coredesktop-dev
+
+Tools for working on [CoreDesktop](https://gitea.federated.computer/Federated_Computer/coredesktop)
+itself. Only contributors need these, so they're a CoreDesktop sibling project
+rather than part of CoreDesktop.
+
+## Install
+
+```
+sibling add <url of this repo>
+```
+
+It asks where your working copy of CoreDesktop is (default
+`~/Projects/coredesktop`), and offers to clone it there. CoreDesktop's `update`
+keeps this project current from then on. To change the working copy, run
+`sibling add` again.
+
+It installs shellcheck, bats, tea (Gitea's CLI), QEMU and xorriso.
+
+## Why: the two copies of CoreDesktop
+
+A developer's machine has two copies of CoreDesktop:
+
+- **Deployed**, in `~/.local/share/coredesktop`: what the machine runs, and
+  what `update` pulls (fast-forward only). Never edit it: a changed tracked
+  file stops `update` from pulling.
+- **Working**, e.g. `~/Projects/coredesktop`: where you make changes. Nothing
+  runs from here unless you run it.
+
+These commands let you test the working copy without touching the deployed one.
+
+## Commands
+
+| Command | |
+|---------|---|
+| `coredesktop-dev doctor` | Check the tools, the working copy, and that the deployed copy can still update |
+| `coredesktop-dev check [--fast]` | `make lint` and `make test` in the working copy, plus shellcheck on scripts not committed yet. `--fast`: shellcheck only |
+| `coredesktop-dev try [--keep] [cmd...]` | Run the working copy's code as if it were installed, in a throwaway home with its own D-Bus session and no display, e.g. `coredesktop-dev try configure --list`. sudo, yay, pacman and systemctl still change this machine |
+| `coredesktop-dev deployed [status\|restore]` | Show the deployed copy's state, or undo local changes to it (after asking) |
+| `coredesktop-dev hooks [status\|install\|remove]` | A pre-push hook in the working copy that runs `check` first. `git push --no-verify` skips it |
+| `coredesktop-dev smoketest ...` | Test install and update on virtual machines (below) |
+
+Each takes `--help`. In a Flatpak (an editor's built-in terminal, say),
+coredesktop-dev runs itself on the host with `flatpak-spawn --host`.
+
+## Smoketest
+
+Runs CoreDesktop's end-to-end scenarios, in `smoketest/` in the working copy,
+on throwaway QEMU virtual machines: a fresh install, updates of all kinds,
+failing migrations and hooks, low disk space, a month-old machine, and more.
+See `smoketest/README.md` in CoreDesktop for what's tested and how to add a
+scenario.
+
+```
+coredesktop-dev smoketest list               # the scenarios
+coredesktop-dev smoketest run                # the quick ones (tier pr), against HEAD
+coredesktop-dev smoketest run --tier all     # everything; hours
+coredesktop-dev smoketest run 40 43          # just these
+coredesktop-dev smoketest run --keep 40      # on failure, leave the VM up to look around
+coredesktop-dev smoketest shell installed    # SSH into a throwaway VM
+```
+
+What it needs: KVM (virtualization turned on in the firmware), about 8 GB of
+RAM and 4 CPUs per VM (`SMOKETEST_MEMORY`, `SMOKETEST_CPUS`), and disk space in
+`~/.cache/coredesktop-dev/smoketest`: VM disks grow as large as a real install,
+about 50 GB, and each run's VM disk is deleted when it's done.
+
+The first run builds two images, which takes a while:
+
+- **base**: Arch's official cloud image, with GNOME added the way archinstall's
+  desktop profile installs it. The user `tester` (password `tester`) logs in to
+  GNOME automatically and has passwordless sudo.
+- **installed**: base after CoreDesktop's `install.sh`, at the commit your
+  branch started from. Scenarios on this image first `update` it to the commit
+  under test. Rebuild it now and then (`smoketest images installed`) so that
+  update has less to catch up on.
+
+Downloaded Arch packages are kept in the cache folder and shared with every
+VM, so they download once. Flatpaks aren't cached.
+
+To watch a VM's screen, set `SMOKETEST_VNC=1` and connect a VNC viewer to
+`127.0.0.1:5901`.
+
+## Developing this project
+
+```
+make check    # shellcheck + bats
+```
+
+The tests use fake commands, like CoreDesktop's: nothing touches the machine,
+and the smoketest tests use a fake QEMU.