From a target name to a VM

from .url to .run for users for contributors

image-garden make SYSTEM.run works back from the launcher to the image URL, then builds ten files in order - URL and filename files, the verified download and its link, user-data, meta-data, the seed ISO, the firmware copies, the provisioned overlay and the launcher - redoing only what is missing or out of date.

On the map: runtime

▶ Watch this deck — 8 scenes, ~6 min

Worth seeing first

01 Working backwards from the file you want

THE TARGET CHAIN $ image-garden make ubuntu-cloud-24.04.x86_64.run .run launcher .qcow2 disk firmware copies the download seed ISO .url, .filename user-data, meta-data make asks, right to left: what does this file need? then builds left to right: ten steps, the URL first, the launcher last
image-garden make ubuntu-cloud-24.04.x86_64.run: make asks what the .run launcher needs (the disk and the firmware), what the disk needs (the download, the seed ISO and the firmware), what those need (the cloud-init files and the URL), then builds forwards in ten steps from the URL to the launcher

make works back from ubuntu-cloud-24.04.x86_64.run to the image URL, then builds forwards: ten files, each made only when it is missing or older than what it is made from.

When you type image-garden make and a system's .run file, make doesn't start at the beginning. It starts from the file you asked for and asks what that needs. The launcher needs the prepared disk and the firmware. The disk needs the download, a seed ISO and the same firmware. The seed needs two cloud-init files, and the download needs a URL. So make walks backwards, all the way to the URL, then builds forwards, one file at a time, ten steps in all. This deck follows those steps for Ubuntu 24.04 on x86, and shows what happens when one of them fails.

Details and sources

Details

  • The launcher X.run depends on the makefiles and, order-only, on X.qcow2, X.efi-code.qcow2 and X.efi-vars.qcow2 (rulegen.py:593-599).
  • The disk X.qcow2 depends on the download link $(GARDEN_DL_DIR)/ubuntu/X.qcow2, X.seed.iso and the two firmware copies (rulegen.py:601-602).
  • The seed depends on X.user-data and X.meta-data (010-qemu.mk:268-278); the download link on X.url and X.filename (rulegen.py:511-514); the firmware copies on efi-code.x86_64.img and efi-vars.x86_64.img (010-qemu-x86_64.mk:316-329).
  • This is the chain of an x86_64 EFI system. A BIOS system has no firmware files (rulegen.py:612-628); s390x and ppc64 have none either; aarch64, riscv64 and loongarch64 have their own firmware rules. See boot types.
  • The ten steps are listed, in the order image-garden make -n prints them, in the reference below.

02 Four steps in the cache

STEPS 1 TO 4 · THE CACHE ~/.cache/image-garden/dl/ubuntu/ 1 ubuntu-cloud-24.04.x86_64.url https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img 2 ubuntu-cloud-24.04.x86_64.filename noble-server-cloudimg-amd64.img no fixed URL? a small program looks it up when make runs: .url is a real file 3 noble-server-cloudimg-amd64.img image-garden download-with-sha256sums … fetched and checked 4 ubuntu-cloud-24.04.x86_64.qcow2 -> noble-server-cloudimg-amd64.img a link named after the system every later step uses the link, not the distribution's file name
Steps one to four in ~/.cache/image-garden/dl/ubuntu: ubuntu-cloud-24.04.x86_64.url holds the image URL, .filename holds noble-server-cloudimg-amd64.img, the download helper fetches and checks that image, and the link ubuntu-cloud-24.04.x86_64.qcow2 points at it; systems without a fixed URL look it up when make runs

In ~/.cache/image-garden/dl/ubuntu/: .url, .filename, the verified image, and the link ubuntu-cloud-24.04.x86_64.qcow2 that every later step uses.

The first four steps happen in the download cache, in a directory named after the distribution. make writes the image's URL into a small .url file, and the name to save it under into a .filename file. For our system that's just the last part of the URL. Why the extra files? Some distributions have no fixed URL, and a small program looks it up when make runs, so make needs a file to depend on. Then the download helper fetches and checks the image. Last, make adds a link named after the system, pointing at the image. Every later step refers to that link, not to the distribution's own file name.

Details and sources

Details

  • The group directory $(GARDEN_DL_DIR)/ubuntu is made with mkdir -p (rulegen.py:447-450).
  • Step 1, X.url, depends on the makefiles and holds the URL key, written out with echo, or the output of URLProgram (rulegen.py:520-530).
  • Step 2, X.filename, holds LocalFilename when the section sets it, otherwise the URL's last path component; for a URLProgram system it is worked out from the .url file, with URLPattern and LocalFilenameTemplate when they are set (rulegen.py:532-591, rulegen.py:782-799).
  • Step 3 runs image-garden download-with-sha256sums $(cat X.url) <SHA256SUMS URL> $(GARDEN_DL_DIR)/ubuntu $(cat X.filename); step 4 makes the link with GARDEN_SYMLINK, ln -sfn to a temporary name and one mv -fT, so that two makes can make it at once (rulegen.py:510-514, 000-garden.mk:58-64). Steps 3 and 4 are one recipe.
  • The URL on the slide is the section's URL (ubuntu.ini:237-242). The path on the slide is the default cache of a native or source install; see where files live.
  • Derived (run in a scratch tree): because X.url depends on the makefiles, an upgrade or an edit of .image-garden.mk rewrites it; the cached image is then older than X.url, so the download recipe runs on every later make and checks the image again without fetching it.

03 The seed and the firmware, beside your project

STEPS 5 TO 8 · YOUR PROJECT in your project directory, or in .image-garden/ when it exists ubuntu-cloud-24.04.x86_64.user-data ubuntu-cloud-24.04.x86_64.meta-data ubuntu-cloud-24.04.x86_64.seed.iso label cidata EDK2 firmware: host or snap efi-code.x86_64.img efi-vars.x86_64.img copied once, shared by every x86 system ubuntu-cloud-24.04.x86_64.efi-code.qcow2 ubuntu-cloud-24.04.x86_64.efi-vars.qcow2 each system's own copies: the machine writes its boot settings into the variable store after step 8, everything the disk needs is ready
Steps five to eight in the project directory: the user-data and meta-data are packed into a seed ISO labelled cidata; the EDK2 firmware from the host or the snap is copied once into efi-code.x86_64.img and efi-vars.x86_64.img, shared by every x86 system; each system then gets its own .efi-code.qcow2 and a writable .efi-vars.qcow2

Steps 5 to 8: .user-data and .meta-data, the cidata seed ISO, efi-code.x86_64.img and efi-vars.x86_64.img copied once, and the system's own .efi-code.qcow2 and .efi-vars.qcow2.

The next four steps happen in your project directory, or in .image-garden when it exists. make writes the user-data and the meta-data, the two files cloud-init reads on first boot, and packs them into a seed ISO labelled cidata. Then the firmware. The firmware code and a blank variable store are copied once from the EDK2 firmware on your host, or in the snap, and shared by every x86 system in the directory. Each system then gets its own qcow2 copy of both, because the machine writes its boot settings into the variable store. After step eight, everything the disk needs is ready.

Details and sources

Details

  • image-garden make runs make with -C .image-garden when that directory exists, else in the current directory (image-garden:982-993).
  • Step 5: X.meta-data and X.user-data are written from the templates; both depend on the makefiles, and the user-data also on the project's .image-garden.mk (rulegen.py:460-471). make -n prints the user-data first.
  • Step 6: %.seed.iso is made by xorriso -as genisoimage … -volid cidata with the two files grafted in as user-data and meta-data (010-qemu.mk:263-278).
  • Step 7: efi-code.x86_64.img and efi-vars.x86_64.img are copied with cp --preserve=timestamps from the first file found in a search list of host paths, then the snap's QEMU component, then GARDEN_X86_64_PREFIX (010-qemu-x86_64.mk:260-280, 010-qemu-x86_64.mk:316-322). When none is found make warns "please install x86_64 edk2 firmware".
  • Step 8: %.x86_64.efi-code.qcow2 and %.x86_64.efi-vars.qcow2 are made with qemu-img convert -f raw -O qcow2 (010-qemu-x86_64.mk:324-329). The code is attached read-only as pflash unit 0 and the variables writable as unit 1 (010-qemu-x86_64.mk:21-22).
  • That the guest firmware stores its boot entries in the variable store is general UEFI behaviour (derived).

04 The disk, then the launcher

STEPS 9 AND 10 9 · the overlay and its provisioning boot 10 · the .run launcher ubuntu-cloud-24.04.x86_64.run: $(MAKEFILE_LIST) | ubuntu-cloud-24.04.x86_64.qcow2 ….efi-code.qcow2 ….efi-vars.qcow2 after the bar: order-only the disk is made again the launcher stays as it is $ rm ubuntu-cloud-24.04.x86_64.run written back in a second, nothing boots rewritten when the rules change: image-garden.mk after an upgrade, or your .image-garden.mk
Step nine makes the overlay and provisions it, step ten writes the .run launcher; the launcher's rule lists the disk and firmware after a bar, as order-only prerequisites, so a remade disk keeps the launcher, a deleted launcher is written back without a boot, and the launcher is rewritten only when image-garden.mk or .image-garden.mk changes

ubuntu-cloud-24.04.x86_64.run lists the disk and firmware after a |: they must exist, but a newer disk does not rewrite the launcher. The makefiles, .image-garden.mk included, do.

Step nine is the big one: the overlay on the download, and the boot that provisions it. Step ten writes the .run launcher. Here's a detail that saves you time. The launcher needs the disk to exist, but it doesn't care how old the disk is: make calls that an order-only prerequisite. So when the disk is made again, the launcher stays as it is. And if you delete just the launcher, make writes it back in a second, without booting anything. The launcher is rewritten when image-garden's own rules change, after an upgrade, or when you edit .image-garden.mk.

Details and sources

Details

  • The launcher rule is X.run: $(MAKEFILE_LIST) | $(if $(GARDEN_RUN_REQUIRES_QCOW2),X.qcow2) X.efi-code.qcow2 X.efi-vars.qcow2; the disk rule creates the overlay and runs the provisioning boot in one recipe (rulegen.py:593-610). Prerequisites after | are order-only in GNU make: they are made first if missing, but their time stamps do not make the target out of date.
  • GARDEN_RUN_REQUIRES_QCOW2 ?= 1 (010-qemu.mk:14); set it empty and make X.run writes the launcher without making the disk.
  • $(MAKEFILE_LIST) includes the project's .image-garden.mk, which mk/999-local.mk includes before the generated rules are read (999-local.mk:4-5).
  • Run in a scratch tree with make -n: with every file present, X.run is up to date; with a newer X.qcow2, still up to date; with X.run deleted, only "Generate launcher script" is printed.
  • The launcher refers to the disk by name, so a remade disk is booted by the old launcher unchanged.

for contributors

In the code

  • The x86_64 EFI template is ruleset_x86_64_efi; the BIOS, aarch64, riscv64, loongarch64, s390x and ppc64 templates use the same order-only pattern (rulegen.py:593-724).

05 When a step fails half-way

WHEN A STEP FAILS 1 2 3 4 5 6 7 8 9 10 steps 1 to 8 done · the provisioning boot in step 9 fails · 10 not reached .DELETE_ON_ERROR: at the top of the rules: a failed recipe's file is deleted ubuntu-cloud-24.04.x86_64.qcow2 the half-made disk: deleted ubuntu-cloud-24.04.x86_64.qcow2.log its console log: kept, read it $ image-garden make ubuntu-cloud-24.04.x86_64.run starts again at step 9, the first missing file spared: the .partial download, resumed next time, and the links in the cache, which another make may be using
Ten steps; steps one to eight are done and step nine, the provisioning boot, fails; .DELETE_ON_ERROR makes make delete ubuntu-cloud-24.04.x86_64.qcow2 while ubuntu-cloud-24.04.x86_64.qcow2.log stays to be read; running the command again starts at step nine; a partial download and the links in the cache are spared

.DELETE_ON_ERROR removes a target whose recipe failed. A failed provisioning boot leaves no .qcow2 but keeps .qcow2.log; the next make starts again at step 9.

Builds fail: the network drops, the disk fills up, or the provisioning boot goes wrong. image-garden's rules start with .DELETE_ON_ERROR, which tells make to delete a file whose recipe failed. Otherwise a half-made file would look up to date next time, and you'd boot a broken disk. So when provisioning fails, the disk is deleted, but its console log stays, and that's where to look. Run the same command again and make picks up at the first missing file. Two things are spared: a partial download, which is resumed, and the links in the cache, which another make may be using.

Details and sources

Details

  • mk/000-garden.mk starts with .DELETE_ON_ERROR:, "so that a partially built file, like firmware that was copied but not resized, is not considered up to date on the next invocation" (000-garden.mk:4-7). It comes first in image-garden.mk, after the list of systems.
  • The provisioning boot is set -o pipefail && <QEMU command> 2>&1 | tee X.qcow2.log, so a QEMU failure fails the recipe; the log is not a target and stays (rulegen.py:605-609).
  • Checked with GNU make 4.4.1 on a small makefile (derived): with .DELETE_ON_ERROR and .PRECIOUS: %.qcow2 %.img, a failing explicit x.qcow2 rule still deletes x.qcow2, because a pattern in .PRECIOUS covers files made by pattern rules, not explicit targets. make also deletes a target it was making when you press Control C.
  • The download link in the cache is .PRECIOUS: "Another make may download the same image, and make the same link, at the same time: a make that is interrupted must not remove it" (rulegen.py:494-496).
  • The image itself is not a make target: the helper downloads it to FILE.partial, which it keeps on failure or interrupt so that the next run resumes (image-garden:528-537).

06 Ask make what is left

WHAT IS LEFT $ image-garden make -n ubuntu-cloud-24.04.x86_64.run make: 'ubuntu-cloud-24.04.x86_64.run' is up to date. finished $ rm ubuntu-cloud-24.04.x86_64.seed.iso $ image-garden make -n ubuntu-cloud-24.04.x86_64.run xorriso -as genisoimage … -volid cidata … qemu-img create -f qcow2 -b …/ubuntu-cloud-24.04.x86_64.qcow2 … 64G qemu-system-x86_64 … 2>&1 | tee ubuntu-cloud-24.04.x86_64.qcow2.log the seed the overlay provisioning no launcher $ rm ubuntu-cloud-24.04.x86_64.run; image-garden make -n … echo "#!/bin/bash" >ubuntu-cloud-24.04.x86_64.run … one step missing or older than its inputs, then what depends on it, and nothing else
Three dry runs of image-garden make -n ubuntu-cloud-24.04.x86_64.run: on a finished system make says the launcher is up to date; after deleting the seed ISO it prints the seed, the overlay and the provisioning boot but not the launcher; after deleting the launcher it prints only the launcher

image-garden make -n on a finished system: up to date. Without the seed: seed, overlay, provisioning. Without the launcher: the launcher alone.

Not sure what a command will redo? Add -n, and make prints the steps it would run without running them. On a finished system it just says the launcher is up to date. Delete the seed ISO and try again: -n now shows three steps, the seed, the overlay and the provisioning boot, because the disk is made from the seed. The launcher isn't on the list. Delete only the launcher, and you get one step. That's the chain at work: make redoes what's missing or older than its inputs, then what depends on it, and nothing else.

Details and sources

Details

  • -n prints the commands without running them (README.md:514-519).
  • The three cases were run with the image-garden script and an image-garden.mk built from the v0.8.0 tree, whose rules for these files are the same at the commit in garden.commit, on a scratch project whose files were created in build order. The output on the slide is abridged: -n also prints the printf lines of the banners and every line of the launcher.
  • The disk is made from the seed (X.qcow2: … X.seed.iso …), so a new seed means a new overlay and a new provisioning boot (rulegen.py:601-609); the launcher has the disk only as an order-only prerequisite (rulegen.py:594-594).
  • Deleting the disk alone gives two steps: the overlay and the provisioning boot.
  • The message is GNU make's; a translated make prints it in your language.

07 Where to go from here general version

ROADS The target chain Download and verify locks, resumes, retries Overlay and first boot the disk, step nine Provisioning runs once what cloud-init does Where files live cache, project, runtime
Four roads from the target chain: download and verify, the overlay and the provisioning boot, the first boot, and where files live

Next: downloads, the overlay, the first boot and where files live.

That's the whole chain: four steps in the cache, four beside your project, then the disk and the launcher, with make doing only what's missing. To go deeper into one link of it, the download deck explains the locks, resumes and checksum retries of step three. The overlay deck covers the disk and its provisioning boot. First boot says what cloud-init does with the seed. And where files live covers the cache, your project directory and the runtime directory.

Details and sources

08 Where to go from here for contributors in place of the general version

ROADS The target chain Download and verify locks, resumes, retries Overlay and first boot the disk, step nine Provisioning runs once what cloud-init does Where files live cache, project, runtime rulegen.py for contributors
Five roads from the target chain: download and verify, the overlay and the provisioning boot, the first boot, where files live, and what rulegen.py emits

Next: downloads, the overlay, the first boot, where files live and how rulegen.py writes the rules.

That's the whole chain: four steps in the cache, four beside your project, then the disk and the launcher, with make doing only what's missing. To go deeper into one link of it, the download deck explains the locks, resumes and checksum retries of step three. The overlay deck covers the disk and its provisioning boot. First boot says what cloud-init does with the seed. Where files live covers the cache and the runtime directory. And contributors can see how rulegen writes these rules for every section.

Details and sources

Read more

Basis of the statements on this page

The rules were read in the image-garden source at the commit in garden.commit ("code"). The order of the steps and the three dry runs were produced by running image-garden make -n with the image-garden script and an image-garden.mk built from the v0.8.0 tree, whose rules for these steps are the same, in a scratch project with a fake cache ("run"). What GNU make does with .DELETE_ON_ERROR, .PRECIOUS and order-only prerequisites was checked on small makefiles with GNU make 4.4.1 ("derived").

The ten steps, in the order make runs them

For image-garden make ubuntu-cloud-24.04.x86_64.run, with X the system name and DL the download cache (~/.cache/image-garden/dl for a native or source install). Files 5 to 10 are made in the project directory, or in .image-garden/ when it exists.

StepFileMade byMade again when
1DL/ubuntu/X.urlecho of the URL key, or the URLProgram outputthe makefiles change
2DL/ubuntu/X.filenameLocalFilename, or the URL's last componentthe makefiles change (or X.url, for URLProgram systems)
3DL/ubuntu/noble-server-cloudimg-amd64.imgimage-garden download-with-sha256sumsmissing, or failing its check
4DL/ubuntu/X.qcow2, a link to step 3ln -sfn and mv -fTX.url or X.filename is newer than the image
5X.user-data, X.meta-datathe cloud-init templatesthe makefiles, or .image-garden.mk, change
6X.seed.isoxorriso -as genisoimage -volid cidatastep 5 is remade
7efi-code.x86_64.img, efi-vars.x86_64.imgcp from the EDK2 firmwarethe source firmware is newer
8X.efi-code.qcow2, X.efi-vars.qcow2qemu-img convertstep 7 is remade
9X.qcow2 and X.qcow2.logqemu-img create -b on step 4, then the provisioning bootsteps 4, 6 or 8 are newer
10X.runthe launcher macrothe makefiles change, or it is missing

image-garden make clean removes steps 4 to 10 (the link in step 4 included); image-garden make distclean also removes steps 1 to 3, the download with its .url and .filename (rulegen.py:473-492). See where image-garden keeps its files.

Sources: rulegen.py:447-610, 010-qemu.mk:263-278, 010-qemu-x86_64.mk:316-329.

"The makefiles" is $(MAKEFILE_LIST): image-garden.mk and the project's .image-garden.mk. make compares the time of the link in step 4 by following it to the image, so after the makefiles change, step 4 runs on every make (the helper checks the image again but does not fetch it) until the image itself is downloaded again (run).

Banners

BannerStep
Resolve URL for X1
Resolve local filename for X2
Download and verify base image for X3 and 4
Generate cloud-init user-data for X, Generate cloud-init meta-data for X5
Create cloud-init seed ISO X.seed.iso6
Prepare writable qcow2 for X9, the overlay
Provision X9, the boot
Generate launcher script for X10

The section banners, framed with =, are cut to 44 characters; the other titles are underlined with dashes (000-garden.mk:32-41).

Other systems

  • BIOS systems (Boot=bios) have no steps 7 and 8; s390x and ppc64 systems neither.
  • aarch64, riscv64 and loongarch64 EFI systems use their own firmware files (efi-code.ARCH.img and so on).
  • Ubuntu Core downloads an .img.xz and converts it to qcow2 in the cache before the link is made; see Ubuntu Core.
  • A named instance BASE@NAME.ARCH has its own steps 5, 6, 8, 9 and 10 on the base system's link; see named instances.

Special targets

TargetWhereEffect
.DELETE_ON_ERROR:000-garden.mk:7a target whose recipe fails is deleted
.PRECIOUS: DL/GROUP/X.qcow2rulegen.py:494-496the cache link is kept when make is interrupted
.PRECIOUS: %.qcow2 %.img010-qemu.mk:334files made by the convert pattern rules are kept; the explicit X.qcow2 overlay is not covered (derived)
X.run with the disk after the barrulegen.py:594-594the disk and firmware are order-only prerequisites of the launcher

Roads from here

RUNTIME · make rules and the CLI

FIRST BOOT · cloud-init changes

BUILD TIME · data and rules