# Agent notes How to build and test this image as a coding agent. Follow [Style](#style) for every change. ## Style - Keep it simple. Prefer fewer files and fewer lines. Delete what isn't needed. - Follow the defaults and conventions of each tool and language. Only set an option when the default doesn't work, and say why. - Divide code and config into parts (files, directories, sections) that each stand on their own: reading one part alone tells you what it does and why. - Each fact lives in one place. Elsewhere, refer to it instead of repeating it. - Write plain English in short sentences. - Name each part for what it does. A part without a good name holds things that don't belong together. - A little copying beats a little dependency. Repeat a small piece rather than share it or pull it in from elsewhere. ### File header A file starts with a header, after the shebang if there is one. Leave it out when the name already says it all, as with `.gitignore`. A part made of many files, like a package, needs it in only one of them. For example: ```sh #!/bin/bash # mkosi.version prints the build time in UTC (YYYYMMDDhhmm) and the git # commit. Every build gets a higher version than the one before, which is how # systemd-sysupdate tells that an update is newer. The commit tells which # source an image was built from. ``` - The first sentence starts with the name of the part the file is, and says what it does. That is the name the language or tool uses for it, such as a file name or a package name. - The rest says why, naming the files it works with by path. Files that can't hold comments (JSON, `subuid`, `machine-id`) are explained in the file that uses them. ### Comments - Explain why, not what. Leave out comments that only repeat the code. Try to write clean code instead of many comments. - Put a comment right above the line or block it is about. A short note on one line may go at the end of that line, as a full sentence too. - Write full sentences that start with the name of what they describe: `# ManifestFormat lists the packages and versions in the image.` or `# link prints the tmpfiles line for /etc/$1.` - Separate paragraphs and lists with a line holding only the comment character. - Wrap comments at 80 columns. ## Testing `mkosi vm` boots the image in qemu and needs systemd on the host. Without it, run mkosi in a privileged podman container that boots systemd: ```sh podman build -t mkosi-vm - <<'END' FROM registry.fedoraproject.org/fedora:latest RUN dnf install -y mkosi git-core CMD ["/sbin/init"] END podman run -d --name mkosi --privileged --systemd=always -v :/repo \ -v mkosi-cache:/root/.cache/mkosi -v mkosi-work:/var/tmp -w /repo mkosi-vm podman exec mkosi mkosi genkey # Run this once, if there is no mkosi.key. podman exec -d -t mkosi sh -c 'mkosi -f vm > mkosi.output/vm.log 2>&1' podman exec mkosi mkosi ssh -- systemctl --failed ``` podman resolves paths on the host, so `` is the repository's path there. The volume `mkosi-cache` keeps mkosi's package cache when the container is made again, so builds don't download every package anew. The volume `mkosi-work` keeps mkosi's workspace in /var/tmp off the container's overlayfs. mkosi copies a tree with SELinux labels (as files from the host have) to overlayfs without any xattrs. That drops the file capabilities of newuidmap and newgidmap, and rootless podman fails in the VM. `mkosi vm` needs a terminal, hence `-d -t`; its console goes to the log. `mkosi ssh` runs a command as root, once the VM has booted. For the user `agent`, run `su - agent -c ''`. `mkosi.version` gives every run a new version, so `mkosi vm` without `-f` fails with "has not been built yet". To boot an existing build without a rebuild, pin its version (from `mkosi.output/agent_.raw`): ```sh mkosi --image-version 202611171816.c80e843 vm ```