Snap, container or native package

snap, container, packages for everyone

The same make rules ship as the snap, the OCI container, distribution packages and a source build; they differ in which QEMU runs, where downloads are cached, whether pkgproxy, spread and swtpm come along, and how close they stay to upstream releases.

On the map: start here

▶ Watch this deck — 7 scenes, ~5 min

01 The same rules, three ways in

THREE WAYS IN The snap, Snap Store The container, docker or podman A package, or a source build image-garden.mk the same rules in each ubuntu-cloud-24.04.x86_64.run built the same way by each What differs around the rules which QEMU where downloads go pkgproxy, spread, swtpm how current
Three ways in, the snap, the container, and a distribution package or a source build, all carry the same image-garden.mk, which builds ubuntu-cloud-24.04.x86_64.run the same way; what differs is which QEMU runs, where downloads go, which extras come along and how current each is

The snap, the container and distribution packages or a source build all carry the same image-garden.mk. They differ in QEMU, cache location, the extras that come along, and how current they are.

Before your first image-garden make, you need image-garden itself, and there are three ways to get it. The snap, from the Snap Store. The container, which you run with docker or podman. Or a package from your distribution, or a build from source. Whichever you pick, the make rules inside are the same, so ubuntu-cloud-24.04.x86_64 is built the same way by each. What differs is everything around them: which QEMU runs, where the downloads are kept, whether pkgproxy, spread and swtpm come along, and how close each stays to the newest release. This deck takes them one at a time.

Details and sources

Details

  • The README compares the three installs in one table: availability, QEMU, architectures, EFI firmware, swtpm, spread, pkgproxy, virtiofsd and the cache (README.md:91-112). The full comparison is under this deck.
  • Every install runs the same image-garden script on the same image-garden.mk, built from data/*.ini and mk/*.mk by the top-level Makefile (Makefile:48-64); the script runs make -f on that file (image-garden:982-993).

Read more

02 The snap

THE SNAP $ snap install image-garden the install hook installed at once QEMU for your host pkgproxy, a service spread (configure hook) added when you ask QEMU for other architectures spread-plus swtpm QEMU built from source, one patch, as in the container ~/snap/image-garden/common/cache downloads, kept across refreshes strict confinement: keep your projects under your home directory
snap install image-garden runs the install hook, which installs QEMU for the host architecture and pkgproxy as components at once, and the configure hook adds spread; the other QEMU components, spread-plus and swtpm are added when you ask. The QEMU is built from source with one patch, downloads live in ~/snap/image-garden/common/cache, and strict confinement asks you to keep projects under your home directory

snap install image-garden adds QEMU for the host architecture and pkgproxy as components, and the configure hook adds spread; other QEMUs, spread-plus and swtpm come on demand. Downloads live in ~/snap/image-garden/common/cache.

The snap is one command: snap install image-garden. Its install hook adds two components straight away: QEMU for your own machine's architecture, and pkgproxy, the caching proxy, which runs as a service of the snap and which guests use by default. Right after it, the configure hook adds spread. QEMU for the other architectures, spread-plus and swtpm are components too, added when you ask for them. The snap's QEMU is built from source with one small patch, the same one the container carries. Downloads go to ~/snap/image-garden/common/cache, which survives refreshes. Strict confinement means a few paths move, so keep your projects under your home directory.

Details and sources

Details

  • The install hook runs snapctl install +qemu-<host arch> +pkgproxy, unless the snap was sideloaded (a revision such as x1) (snap/hooks/install:6-14).
  • The configure hook, which snapd runs at install too, installs +spread while the spread-variant setting is empty (snap/hooks/configure:83-92); the README says so (README.md:163-169).
  • The components are spread, spread-plus, qemu-x86-64, qemu-aarch64, qemu-riscv64, qemu-s390x, qemu-ppc64, qemu-loongarch64, pkgproxy and swtpm (snap/snapcraft.yaml:45-119). The README shows how to add one: snap install image-garden+qemu-aarch64 (README.md:309-334).
  • The snap builds QEMU with qemu-patches/guestfwd-unix-socket.patch (snap/snapcraft.yaml:341), the patch the container applies too (Dockerfile:29-32).
  • In the snap, GARDEN_CACHE_DIR is $SNAP_USER_COMMON/cache, which is ~/snap/image-garden/common/cache (mk/000-garden.mk:9-12). The common directory is not tied to a revision (derived from snapd's layout).

03 The container

THE CONTAINER the image-garden container one image, for x86_64 and aarch64 hosts QEMU for six guest architectures, patched swtpm Secure Boot firmware $ docker run --device /dev/kvm \ image-garden:latest image-garden make ubuntu-cloud-24.04.x86_64.run --volume $HOME/.cache/image-garden:/var/cache/image-garden \ not inside pkgproxy, by PKGPROXY_URL spread, added by CI images
The container image, for x86_64 and aarch64 hosts, carries a patched QEMU for six guest architectures, swtpm and Secure Boot firmware; pkgproxy and spread are not inside. docker run passes --device /dev/kvm and a volume for /var/cache/image-garden, then runs image-garden make

One image with QEMU for six architectures, swtpm and OVMF. Run it with --device /dev/kvm and a volume at /var/cache/image-garden; name a pkgproxy with PKGPROXY_URL.

The container suits you when you'd rather install nothing on the host, or want every CI runner to carry exactly the same tools. It's one image, for 64-bit x86 and Arm hosts, with QEMU for all six guest architectures built in, patched like the snap's, plus swtpm and the Secure Boot firmware. You run it with docker or podman, and pass it two things: the KVM device, and a volume for the cache at /var/cache/image-garden. pkgproxy isn't inside; you point the container at one with PKGPROXY_URL. spread isn't either, which is why the GitLab CI components build their own image on top of this one.

Details and sources

Details

  • The first build stage builds QEMU from the release tarball, checked by its sha256, with the guestfwd patch, for x86_64, aarch64, riscv64, s390x, ppc64 and loongarch64 (Dockerfile:5-54).
  • The final image installs ovmf, swtpm, curl, make, xorriso, xz-utils and git, sets GARDEN_CACHE_DIR=/var/cache/image-garden and declares that directory a volume (Dockerfile:73-104). It has no spread, no pkgproxy and no entrypoint.
  • The README's run example: docker run --device /dev/kvm --volume $HOME/.cache/image-garden:/var/cache/image-garden image-garden:latest, and the same with podman (README.md:342-382).
  • CI builds the image on an x86_64 and an aarch64 runner and, for a tag, publishes one image with both, tagged with the tag and latest (.gitlab-ci.yml:1231-1278).
  • The GitLab CI components build on this image and add spread; see the CI projects.

04 Distribution packages

DISTRIBUTION PACKAGES Arch Linux (AUR) Debian openSUSE Fedora the image-garden package from your distribution its QEMU its firmware its swtpm architectures you can boot: the emulators you installed pkgproxy: name one with PKGPROXY_URL spread: a package of its own $XDG_CACHE_HOME/image-garden by default ~/.cache/image-garden the same rules, systems and commands as everywhere else
Arch Linux (AUR), Debian, openSUSE and Fedora package image-garden. A package uses the distribution's QEMU, firmware and swtpm, so the architectures you can boot are the emulators you have installed; pkgproxy is named with PKGPROXY_URL, spread is a separate package, and downloads go to $XDG_CACHE_HOME/image-garden. The rules, systems and commands are the same

Packages for Arch Linux (AUR), Debian, openSUSE and Fedora use the host's QEMU, firmware and swtpm. pkgproxy comes from PKGPROXY_URL; downloads go to $XDG_CACHE_HOME/image-garden.

Several distributions package image-garden: Arch Linux in the AUR, Debian, openSUSE and Fedora. Install it the way you install anything else there. The difference from the snap and the container is that a package uses what your distribution already has: its QEMU, its firmware, its swtpm. So the architectures you can boot are the emulators you've installed. pkgproxy isn't bundled; name one with PKGPROXY_URL and guests reach it over QEMU's ordinary network. spread, if you want it, is a package of its own. Downloads go to image-garden's folder in your home cache directory. The rules, the systems and the commands are the same as everywhere else.

Details and sources

Details

  • The README links packages for Arch Linux (AUR), Debian, openSUSE and Fedora; its table says a package uses the system's QEMU, EFI firmware and swtpm, spread is a system package, pkgproxy works "With PKGPROXY_URL", and the cache is $XDG_CACHE_HOME (README.md:96-112).
  • Outside the snap, GARDEN_CACHE_DIR is $XDG_CACHE_HOME/image-garden, and XDG_CACHE_HOME defaults to ~/.cache (mk/000-garden.mk:9-12).
  • With PKGPROXY_URL set, the host is resolved to an IPv4 address when make runs and guests reach it through QEMU's user network; no guestfwd is added (mk/010-qemu.mk:20-44). The snap's socket modes need the patched QEMU; a package never uses them.
  • The emulator is qemu-system-<arch> from PATH (mk/010-qemu-x86_64.mk:4); a distribution QEMU does not carry the guestfwd patch.
  • Distribution packages may be older than the upstream release (the maintainer's statement).

05 Building from source

FROM SOURCE $ make $ sudo make install list of systems make image-garden.mk /usr/local/include/image-garden.mk /usr/local/bin/image-garden you bring the tools curl xorriso qemu-img qemu-system-* swtpm, ovmf: TPM systems a missing tool stops make at the step that needs it an emulator missing: a warning, until a system needs it
make turns image-garden's list of systems into rules and joins them into image-garden.mk; sudo make install puts it in /usr/local/include next to /usr/local/bin/image-garden. The host brings curl, xorriso, qemu-img and the QEMU emulators, plus swtpm and ovmf for the TPM systems; a missing curl, xorriso or qemu-img stops make at once, a missing emulator is a warning until a system needs it

make && sudo make install builds image-garden.mk and installs it with the command under /usr/local. The host needs curl, xorriso, qemu-img and the qemu-system-* emulators.

If your distribution has no package, or you want a commit newer than any release, build it yourself. In a checkout of the tree, run make, then sudo make install. make turns image-garden's list of systems into rules and joins them into image-garden.mk, and install puts that file under /usr/local, next to the image-garden command. You bring the tools: curl, xorriso, qemu-img, and QEMU's system emulators for the architectures you want. The Ubuntu Core systems with a TPM also need swtpm and the ovmf firmware. Each tool is looked for only when a step needs it, so a missing one stops make at the step that uses it.

Details and sources

Details

  • prefix ?= /usr/local; make install puts image-garden in $(bindir) with @PREFIX@, @INCLUDEDIR@, @DOCDIR@ and @VERSION@ filled in, image-garden.mk in $(includedir), the README and NEWS files in $(datarootdir)/doc/image-garden and the man page in $(man1dir); includedir and datarootdir default from prefix but can be set on their own (Makefile:3-46).
  • image-garden.mk is data/000-systems.mk, the sorted mk/*.mk and the sorted data/050-*.gen.mk joined, each .gen.mk written by rulegen.py from one .ini (Makefile:48-64).
  • The README asks for curl, qemu-system-x86_64, qemu-system-aarch64, qemu-system-riscv64, qemu-system-s390x, qemu-system-ppc64, qemu-system-loongarch64, qemu-img and xorriso, "or the emulators of the architectures you use", and swtpm with the ovmf Secure Boot firmware for the TPM systems (README.md:114-126).
  • xorriso and curl are $(error ...) when missing (mk/000-garden.mk:20-21), as is qemu-img (mk/010-qemu.mk:3); a missing qemu-system-x86_64 is a $(warning ...) (mk/010-qemu-x86_64.mk:4), and the recipe that runs it fails later (derived).
  • make check runs the project's own checks (shellcheck, mypy, the rulegen and download tests).

Read more

06 How current each one is

HOW CURRENT the image-garden tree stable snap container: version and latest on each release tag edge snap every night distribution packages their distribution's schedule may be older than the upstream release the maintainer's statement $ image-garden version $ image-garden news
The image-garden tree becomes a stable snap and a container tagged with the version and latest on every release tag, and an edge snap every night; distribution packages follow their distribution's schedule and may be older than the upstream release. image-garden version and image-garden news show what you have

The snap and the container are built from the tree on every release tag; the snap's edge channel is built nightly. Distribution packages may be older than upstream. image-garden version and image-garden news tell you what you have.

So how new is what you get? The snap and the container are built from the image-garden tree itself. A release tag becomes a stable snap, and a container image tagged with the version and with latest. The snap's edge channel is built every night from the newest commit. Distribution packages follow their distribution's own schedule, and the maintainer's word on this is plain: packages such as Debian's and Fedora's may be older than the upstream release. To check what you have, run image-garden version, and image-garden news prints what changed in it.

Details and sources

Details

  • The snap's version comes from git describe: a commit that is exactly a tag gets that version and grade stable, any other commit TAG+gitN.HASH and grade devel (snap/snapcraft.yaml:271-299).
  • The snap is published through Launchpad by the snap-edge and snap-stable jobs; a nightly schedule exists only to build edge (.gitlab-ci.yml:26-33, .gitlab-ci.yml:128-129).
  • The container is published for a tag only, as the tag and as latest (.gitlab-ci.yml:1257-1278).
  • Distribution packages, such as Debian's and Fedora's, may be older than the upstream release: the maintainer's statement, not in the source.
  • image-garden version prints image-garden VERSION; image-garden news [N] prints the last N "Changes in" sections of NEWS, NEWS.snappy and NEWS.docker, those present in the install (image-garden:909-942). The snap leaves out NEWS.docker, the container NEWS.snappy.

07 Where to go from here

ROADS Three ways in The snap what the install adds Running the container on your own project Distribution packages where to get one A source build make install, make check What the host needs tools and emulators
Roads from the three ways in: the snap, running the container, distribution packages, a source build and what the host needs

Next: the snap, the container, and native packages and source builds, each in its own district.

That's the choice: the snap brings the most, the container carries the same QEMU into any runner, and a package or a source build uses what your system already has. Each has its own district on the map. The snap deck shows what the install adds and what confinement changes. The container deck shows how to run it on your project. And the native packages district covers the distribution packages, a source build, and the tools your host needs.

Details and sources

Read more

Basis of the statements on this page

The comparison table of the README of image-garden, at the commit this map describes (README.md:96-106), checked against the snap's snapcraft.yaml, the Dockerfile and the Makefile ("code"). The age of distribution packages is the maintainer's statement.

The three ways in, side by side

SnapContainerNative package or source
WhereSnap Storecontainer registriesArch (AUR), Debian, Fedora, openSUSE; or make && make install
How currentfollows upstream releasesfollows upstream releasesdistribution packages, such as Debian and Fedora ones, may be older than upstream
QEMUbuilt by the snap, one component per architecturebuilt into the imageyour distribution's
guestfwd unix socket patchyesyesno
Architecturesx86_64, aarch64, riscv64, s390x, ppc64, loongarch64the same sixwhat your QEMU has
UEFI firmwarein the QEMU componentsbuilt with QEMU, plus the ovmf packagesystem packages
swtpm, for +tpm systemsoptional swtpm componentincludedsystem package
spreadthe spread component, added at install; spread-plus on demandnosystem package
pkgproxybundled, or snap set image-garden pkgproxy=…PKGPROXY_URLPKGPROXY_URL
virtiofsdbundled, run as image-garden.virtiofsdnosystem package
QEMU's -snapshot scratch~/snap/image-garden/common/tmp, on disk (qemu-var-tmp:9-20)/var/tmp inside the container/var/tmp, unless TMPDIR says otherwise
Cache~/snap/image-garden/common/cachea volume at /var/cache/image-garden~/.cache/image-garden

The first command in each

InstallCommand
Snapsnap install image-garden; more QEMUs with snap install image-garden+qemu-aarch64, swtpm with snap install image-garden+swtpm
Containerdocker run --device /dev/kvm --volume $HOME/.cache/image-garden:/var/cache/image-garden image-garden:latest image-garden make SYSTEM.run (or podman run)
Distribution packageyour distribution's package manager
Sourcemake && sudo make install, into /usr/local unless prefix= says otherwise

Every install then answers image-garden version and image-garden news.

Roads from here

SNAP · snap-only features

CONTAINER · OCI image

NATIVE · packages