Coredesktop-Dev/README.md

coredesktop-dev

Tools for working on 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 about 45 GB in ~/.cache/coredesktop-dev/smoketest. The images are kept between runs (the installed one is the biggest, around 35 GB), along with the shared package cache and each run's logs. A scenario's own disk only holds its changes to the image, and is deleted when the scenario ends.

To free space, coredesktop-dev smoketest clean deletes old runs' logs, and clean --all deletes everything, so the next run rebuilds the images.

The first run builds two images before any scenario runs: base in a few minutes, installed in an hour or more. Later runs reuse them.

• 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.

The terminal can stay quiet for many minutes while a VM boots or installs. To follow along, tail -f the logs in ~/.cache/coredesktop-dev/smoketest:

• build-base/ and build-installed/, while an image builds: build.log is what the build printed, and serial.log is the VM's console, the place to look when a VM doesn't boot or doesn't answer on SSH.
• runs/<date>-<time>/<scenario>/: scenario.log for each scenario, and serial.log for its VM.

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.