image-garden make and the other commands
the command line for users
image-garden make runs GNU make with image-garden.mk, in .image-garden/ when that directory exists, and builds the system you name. This deck shows what it prints, how to list systems and preview a build, and where the files go; the reference below covers every command, make goal and environment variable.
On the map: runtime
▶ Watch this deck — 7 scenes, ~5 min
Worth seeing first
- How systems are named — how the system name you type is put together
Part of journeys
- Your first garden VM, step 2 of 4 · previous: The image-garden snap · next: The .run script
01 One command for every system
image-garden make SYSTEM.run builds a launcher; SYSTEM.qcow2 builds only the prepared disk. The command is the same in every install.
Most of what you do with image-garden starts with one command: image-garden make, followed by the name of a file you want. Ask for a system's .run file and you get a launcher that boots it. Ask for its .qcow2 and you get just the prepared disk. It's the same command whether you installed the snap, a native package, or you're inside the container. This deck shows what that command really runs, what it prints while it works, how to list the systems, how to preview a build without doing it, and where the files end up.
Details and sources
Details
- The usage text says: "Typically GOAL is 'SYSTEM.qcow2' or 'SYSTEM.run'." (image-garden:889-908).
- The quick start builds
ubuntu-cloud-24.04.x86_64.runand runs it (README.md:69-83); the goalsSYSTEM.ARCH.qcow2andSYSTEM.ARCH.runare described in README.md:552-577. - In the container the command is passed to
docker run … image-garden:latest make …or run inside it; see running image-garden in a container.
Read more
- System names, the snap, the reference below lists every command.
02 GNU make underneath
image-garden make checks /dev/kvm, then runs make -f image-garden.mk with GARDEN_ITSELF and GARDEN_PROJECT_DIR, passing your arguments on.
Under the hood, image-garden make is GNU make with a makefile chosen for you. First the script checks KVM: if /dev/kvm exists but you can't write to it, it prints a large warning and tells you how to fix it, because without KVM every machine is emulated and slow. Then it runs make on image-garden.mk, the rules for every system, and tells make where image-garden itself lives, so recipes can call it back for downloads. Everything else you type goes straight to make: the goal, options such as -n, and variables.
Details and sources
Details
kvm_checkprints a large WARNING when/dev/kvmexists but is not writable, with advice:sudo usermod -aG kvm $LOGNAME, or in CI ($CIset)sudo chmod 666 /dev/kvm. It does not stop the build (image-garden:670-709).image-garden makerunsexec make --warn-undefined-variables GARDEN_ITSELF=… GARDEN_PROJECT_DIR=… -f $GARDEN_INCLUDE/image-garden.mk -C <dir> "$@", where<dir>is.image-gardenwhen it exists (image-garden:982-993).- The makefile ends by including the project's
.image-garden.mk, if there is one (999-local.mk:4-5). - Variables such as
QEMU_MEM_SIZE=4096are make variables: pass them on the command line or set them in.image-garden.mk(README.md:882-888).
Read more
03 What it prints while it works
Banners: Download and verify base image, Prepare writable qcow2, Provision, Generate launcher script. The console of the provisioning boot is kept in SYSTEM.qcow2.log.
While it works, make prints a banner for each big step, with the time. First it downloads and verifies the base image. Then it prepares the writable qcow2 on top of it, and provisions it. Provisioning is the long one: the guest's serial console scrolls past as cloud-init runs, and the same text goes into a log file next to the disk. When the guest powers itself off, make generates the launcher script and finishes. Run the same command again and make has nothing to do, because every file is up to date.
Details and sources
Details
- The banners come from
GARDEN_LOG_SECTION: a border of=, then| %-44.44s %31.31s |with the title anddate -u '+%a, %d %b %Y %H:%M:%S %z', so titles longer than 44 characters are cut (000-garden.mk:32-36). In CI ($CIset) an extra empty row is printed so log viewers keep the gap. - The titles: "Download and verify base image for SYSTEM" (rulegen.py:498-514), "Prepare writable qcow2 for SYSTEM", "Provision SYSTEM" and "Generate launcher script for SYSTEM" (rulegen.py:593-610).
- The provisioning boot's output is piped through
tee SYSTEM.qcow2.log(rulegen.py:609). - The launcher is made after the disk because
SYSTEM.runhas the disk as an order-only prerequisite (rulegen.py:593-596). - The times on the slide are an example.
04 Finding a system to make
image-garden make list-systems lists every system; image-garden make prints help with a random example; image-garden prints the usage of every command.
Which names can you ask for? image-garden make list-systems prints every system it knows, one per line, with its architecture, including the named instances your own project defines. Run image-garden make with no goal at all and you get a short help text, with a system picked at random as an example. And image-garden with no arguments prints the usage of every other command: allocate, discard, ps, rebase, version, news and the download helpers. Between the three you rarely need to guess a name.
Details and sources
Details
helpis the default goal: it printsUsage: image-garden make <SYSTEM>.{run,qcow2}and a system picked with$RANDOM(000-garden.mk:43, 000-garden.mk:72-83).list-systemsprintsGARDEN_SYSTEMS, one per line (000-garden.mk:85-87); named instances add themselves to that list (README.md:536-540).image-gardenwith no arguments,-hor--helpprints the usage of every command (image-garden:889-908).- The system on the slide picked at random is an example.
Read more
05 Look before you build
image-garden make -n SYSTEM.run shows the commands without running them. -B rebuilds everything except complete downloads.
Before you spend ten minutes on a build, you can look at it first. Add -n, or --dry-run, and make prints every command it would run, without running any of them. That's the easiest way to learn the exact QEMU command of the provisioning boot, or to see which download a system needs. Minus capital B goes the other way: it makes everything again, even what's up to date. A download that's already complete isn't fetched twice, though, because an image is only downloaded when it isn't there.
Details and sources
Details
-ndisplays commands without executing them;-Bforces a rebuild, but a complete download is not repeated (README.md:514-519).-nand--dry-runare the same GNU make option.- A complete download is skipped because the downloaded file is kept in the cache and the download helpers only fetch what is missing or does not match its checksum (image-garden:480-559).
- The QEMU command on the slide is abridged;
-nprints it in full.
Read more
06 Where the files go
With a .image-garden/ directory every generated file goes there. .image-garden.mk is read by make, and changing it rebuilds the images that depend on it.
And where do the files go? By default, into the directory you're in: the disk, its log, the seed, the firmware copies and the launcher, about eight files for each system. Create a directory called .image-garden in your project, and image-garden make switches into it, so all of that stays out of your way. Downloads never go there; they stay in the shared cache. And if your project has a .image-garden.mk file, make reads it as well, and editing it marks the system's images as out of date.
Details and sources
Details
image-garden makechanges into.image-garden/when that directory exists (image-garden:982-993); the README lists the eight files made per system (README.md:820-837).- Downloads stay in
$GARDEN_DL_DIR, by default~/.cache/image-garden/dl(image-garden:20-29). SYSTEM.user-datadepends on the project's.image-garden.mk, so editing it rebuilds the user-data, the seed and the disk of every system (rulegen.py:467-468, README.md:854-858).
07 Where to go from here
Next: the .run script, the serial console, the target chain, allocate, where files live, .image-garden.mk and the support matrix.
That's image-garden make: GNU make on the rules for every system, a banner for each step, a list of systems, a dry run when you want one, and a tidy directory for the results. Next, boot what you built with its .run script, and read about the serial console it gives you. The target chain deck goes through every file make builds, in order. Allocate starts a machine in the background with SSH. And to change what a system gets, write a .image-garden.mk for your project.
Details and sources
Read more
Basis of the statements on this page
Read in the image-garden source at the commit in garden.commit ("code"): the image-garden script, mk/*.mk, rulegen.py, the README and the man page image-garden.1. Where the documentation and the code differ, this page follows the code and says so. Nothing was run for this page.
Commands
| Command | What it does |
|---|---|
image-garden make [MAKE-OPTIONS] [GOAL…] | checks /dev/kvm, then runs GNU make on image-garden.mk, in .image-garden/ when it exists (image-garden:982-993) |
image-garden allocate [-p PORT] [--premade] [--nice] [--spread] SYSTEM.ARCH [QEMU-OPTION…] | makes the system unless --premade, starts it in the background with -snapshot and SSH on a local port, prints the address (image-garden:996-1219) |
image-garden discard ADDRESS | stops the machine at localhost:PORT and removes its pid file and TPM state copy (image-garden:1221-1274) |
image-garden discard -a | stops every allocated machine |
image-garden ps [--all] [--stale] | lists allocated machines: address, PID, memory and system; --stale those whose QEMU is gone, --all every entry (image-garden:1276-1358) |
image-garden rebase SYSTEM.ARCH | points a prepared disk's backing file at the matching download in $GARDEN_DL_DIR, with qemu-img rebase -u, so the old download need not exist; takes the system name or its .qcow2 file; fails if there is no matching download (image-garden:943-980) |
image-garden version, --version | prints the version (image-garden:909-911) |
image-garden news [N] | prints the last N releases from NEWS, then the snap's or the container's notes; N defaults to 1 (image-garden:912-942) |
image-garden download-with-sha512sums URL [SUMS-URL] [DIR] [FILENAME] | downloads and checks against a SHA512SUMS list; the list defaults to SHA512SUMS next to the image, DIR to $GARDEN_DL_DIR (image-garden:358-362) |
image-garden download-with-sha256sums URL [SUMS-URL] [DIR] [FILENAME] | the same with a SHA256SUMS list (image-garden:460-464) |
image-garden download-with-sha256sum URL SHA256 [DIR] [FILENAME] | the same with one known hash, which is required (image-garden:562-577) |
image-garden download URL [DIR] [FILENAME] | downloads without a checksum (image-garden:627-630) |
image-garden, -h, --help | prints the usage (image-garden:889-908) |
Options of allocate (README.md:404-424):
| Option | Meaning |
|---|---|
-p PORT | try this port first; a random free port in 5000-9999 otherwise |
--premade | do not make the system, use the images that are there |
--nice | run QEMU with nice; on by default in x11 and wayland sessions |
--spread | print <ADDRESS localhost:PORT> and <FATAL …> for spread, and wait for SSH first |
Make goals
| Goal | What it makes (README.md:506-577) |
|---|---|
help | the default: usage and a random example |
list-systems | every system, with its architecture, including named instances |
SYSTEM.ARCH.run | the launcher, with everything it needs |
SYSTEM.ARCH.qcow2 | only the prepared disk |
all | every system of the host's architecture |
fetch | every download of the host's architecture, for working offline |
clean | removes generated images, logs and support files here; keeps downloads |
distclean | clean, and removes the downloads from the cache |
Useful make options: -n (print, do not run), -B (make again; complete downloads are kept), -j (several systems at once).
The .run script
| Use | Effect |
|---|---|
./SYSTEM.run | boots in the foreground on the serial console; changes are kept |
./SYSTEM.run -snapshot | the same, but changes are thrown away when QEMU exits |
./SYSTEM.run --query | prints vm.memory_mb and system.users.N.username and .password, then exits (010-qemu.mk:57-92) |
./SYSTEM.run ARGS… | any other arguments are added to the QEMU command (010-qemu-x86_64.mk:105) |
./SYSTEM.run of a +tpm system | must be run from its own directory, next to SYSTEM.tpm/ |
Environment variables
| Variable | Used by | Meaning |
|---|---|---|
XDG_CACHE_HOME | all | base of the cache; default $HOME/.cache |
GARDEN_CACHE_DIR | all | the cache; default $XDG_CACHE_HOME/image-garden, in the snap $SNAP_USER_COMMON/cache (image-garden:20-29) |
GARDEN_DL_DIR | all | downloaded images; default $GARDEN_CACHE_DIR/dl |
PKGPROXY_URL | make, downloads | a pkgproxy for guests and image downloads |
GARDEN_DL_PKGPROXY | downloads | a pkgproxy for image downloads alone, http://host:port or unix:/path; set empty to turn downloads through pkgproxy off (image-garden:31-58) |
XDG_RUNTIME_DIR | allocate, discard, ps | pid files, ports and locks, under image-garden/; default /run (image-garden:60-73) |
QEMU_SNAPSHOT_OPTION | allocate | default -snapshot; set empty to keep changes (image-garden:1154) |
GARDEN_SSH_WAIT_TIMEOUT | allocate --spread | seconds to wait for SSH; default 600 (image-garden:1173) |
GARDEN_MEMORY_RESERVE | allocate | MB kept for the host in the memory check; default 2048 in x11 and wayland sessions, 1024 otherwise (image-garden:733-745) |
XDG_SESSION_TYPE | allocate | x11 or wayland turn on nice and the larger reserve |
GARDEN_TPM_RUN_DIR | .run of a +tpm system | where swtpm runs; allocate sets it per port (image-garden:1110-1111) |
QEMU_MEM_OPTION | .run | default -m 2048 (010-qemu.mk:9, 010-qemu.mk:12) |
QEMU_SMP_OPTION | .run | default -smp N: 4 on the host's own architecture, 1 otherwise |
QEMU_DISPLAY_OPTION | .run | default -nographic; allocate uses -display none (010-qemu.mk:13, image-garden:1105) |
QEMU_BOOT_FIRMWARE_OPTION, QEMU_STORAGE_OPTION, QEMU_RNG_OPTION, QEMU_NET_OPTION, QEMU_TPM_OPTION, QEMU_ACCEL_MACHINE_PROP | .run | replace one part of the QEMU command each (010-qemu-x86_64.mk:72-80) |
QEMU_NETDEV_USER_EXTRA | .run | appended to -netdev user; allocate uses it for the SSH port forward (image-garden:1107) |
QEMU_MEM_SIZE, QEMU_IMG_SIZE, QEMU_SMP_<ARCH>, QEMU_CPU_<ARCH> | make | memory, disk size, CPUs and CPU model baked into new launchers; pass on the make command line (README.md:882-899) |
QEMU_SYSTEM_<ARCH>, QEMU_IMG, XORRISO, CURL, SWTPM | make | the tools to run (README.md:915-920) |
The README and the man page list the .run variables, QEMU_NET_OPTION, QEMU_NETDEV_USER_EXTRA, QEMU_STORAGE_OPTION, QEMU_TPM_OPTION and QEMU_ACCEL_MACHINE_PROP among them (README.md:922-947, image-garden.1:638-679); the scripts read them as listed (010-qemu-x86_64.mk:72-80).
Roads from here
SYSTEMS · distributions
- The support matrix — every system you can name
RUNTIME · make rules and the CLI
- The .run script — boot what you built with its .run script
- Working on the serial console — what to expect from the serial console
- From a target name to a VM — every file make builds on the way, in order
- image-garden allocate — start the system in the background with SSH
- Where image-garden keeps its files — where downloads, images and pid files live
FIRST BOOT · cloud-init changes
- Changing what cloud-init does — change what a system gets with .image-garden.mk