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