# Lima Runner Example

Reference scripts for testing compiled Linux kernels in Lima VMs using
cui-cui's remote runner feature. Based on the
[lima-gitlab-runner](https://gitlab.freedesktop.org/bentiss/lima-gitlab-runner)
setup, adapted to work with cui-cui's exec-prefix runner.

## Files

- `cui-cui.toml` -- Example configuration with a Linux build server and a macOS
  Lima test host
- `lima-prepare.sh` -- Prepare script: builds qcow2 from bootc image, starts
  Lima VM, optionally kexecs into a custom kernel
- `lima-cleanup.sh` -- Cleanup script: stops and deletes the VM (runs via
  `trap EXIT`)

## Prerequisites

On the macOS host (the Lima runner):

- [Lima](https://lima-vm.io/) installed (`brew install lima`)
- [Podman](https://podman.io/) installed (for pulling bootc images and running
  bootc-image-builder)
- SSH access configured (key-based, no password prompts)

## Usage

1. Copy `cui-cui.toml` to your kernel repo as `.cui-cui.toml`
2. Adjust hostnames, tags, and paths for your environment
3. Place the prepare/cleanup scripts where the `@file` references point
4. Run: `cui-cui --dispatch .`

## How it works

### qcow2 image caching

The prepare script converts the job's bootc container image (`$CI_JOB_IMAGE`)
to a qcow2 disk using
[bootc-image-builder](https://github.com/osbuild/bootc-image-builder).
The resulting qcow2 is cached by image slug (e.g.
`~/.cache/cui-cui/lima-images/registry-example-com-fedora-bootc-41.qcow2`), so
subsequent runs with the same image skip the conversion step.

Before conversion, the image is customized to add `git-core`, `git-lfs`,
`cloud-init`, `wget`, and `curl` (tools commonly needed for CI). Adjust the
`Dockerfile` in the prepare script for your needs.

### Lima VM lifecycle

1. A Lima VM is created from the cached qcow2 in `--plain` mode with a
   SELinux policy for vsock/clock access and Rosetta enabled for x86_64
   emulation on Apple Silicon
2. If `$LIMA_KEXEC_ARTIFACT` is set (e.g. `vmlinux@build-kernel`), the
   compiled kernel is copied into the VM and kexec'd, replacing the
   bootc kernel with the freshly compiled one
3. Project files (worktree + extracted artifacts) are copied from the
   host into the VM user's home directory so that artifact binaries
   (selftests, etc.) are available at their expected relative paths
4. The job script runs inside the VM via `limactl shell`
5. On exit (success or failure), cleanup stops and deletes the VM instance

### Variables

All job variables are exported before the prepare script runs:

| Variable | Description |
|----------|-------------|
| `$CI_JOB_NAME` | Job name, used as the Lima instance name |
| `$CI_JOB_IMAGE` | Bootc container image to convert to qcow2 |
| `$LIMA_KEXEC_ARTIFACT` | Optional: `path@job` of a kernel artifact to kexec into |
| `$LIMA_IMAGES_PATH` | Optional: where to cache qcow2 images (default: `~/.cache/cui-cui/lima-images`) |
