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
- image-garden make and the other commands — the command that starts the chain and what it prints
01 Working backwards from the file you want
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.rundepends on the makefiles and, order-only, onX.qcow2,X.efi-code.qcow2andX.efi-vars.qcow2(rulegen.py:593-599). - The disk
X.qcow2depends on the download link$(GARDEN_DL_DIR)/ubuntu/X.qcow2,X.seed.isoand the two firmware copies (rulegen.py:601-602). - The seed depends on
X.user-dataandX.meta-data(010-qemu.mk:268-278); the download link onX.urlandX.filename(rulegen.py:511-514); the firmware copies onefi-code.x86_64.imgandefi-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 -nprints them, in the reference below.
02 Four steps in the cache
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)/ubuntuis made withmkdir -p(rulegen.py:447-450). - Step 1,
X.url, depends on the makefiles and holds theURLkey, written out withecho, or the output ofURLProgram(rulegen.py:520-530). - Step 2,
X.filename, holdsLocalFilenamewhen the section sets it, otherwise the URL's last path component; for aURLProgramsystem it is worked out from the.urlfile, withURLPatternandLocalFilenameTemplatewhen 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 withGARDEN_SYMLINK,ln -sfnto a temporary name and onemv -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.urldepends on the makefiles, an upgrade or an edit of.image-garden.mkrewrites it; the cached image is then older thanX.url, so the download recipe runs on every later make and checks the image again without fetching it.
Read more
03 The seed and the firmware, beside your project
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 makeruns make with-C .image-gardenwhen that directory exists, else in the current directory (image-garden:982-993).- Step 5:
X.meta-dataandX.user-dataare 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 -nprints the user-data first. - Step 6:
%.seed.isois made byxorriso -as genisoimage … -volid cidatawith the two files grafted in asuser-dataandmeta-data(010-qemu.mk:263-278). - Step 7:
efi-code.x86_64.imgandefi-vars.x86_64.imgare copied withcp --preserve=timestampsfrom the first file found in a search list of host paths, then the snap's QEMU component, thenGARDEN_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.qcow2and%.x86_64.efi-vars.qcow2are made withqemu-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).
Read more
04 The disk, then the launcher
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 andmake X.runwrites the launcher without making the disk.$(MAKEFILE_LIST)includes the project's.image-garden.mk, whichmk/999-local.mkincludes before the generated rules are read (999-local.mk:4-5).- Run in a scratch tree with
make -n: with every file present,X.runis up to date; with a newerX.qcow2, still up to date; withX.rundeleted, 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).
Read more
05 When a step fails half-way
.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.mkstarts 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 inimage-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_ERRORand.PRECIOUS: %.qcow2 %.img, a failing explicitx.qcow2rule still deletesx.qcow2, because a pattern in.PRECIOUScovers 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
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
-nprints the commands without running them (README.md:514-519).- The three cases were run with the
image-gardenscript and animage-garden.mkbuilt 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:-nalso prints theprintflines 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.
Read more
07 Where to go from here general version
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
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.
| Step | File | Made by | Made again when |
|---|---|---|---|
| 1 | DL/ubuntu/X.url | echo of the URL key, or the URLProgram output | the makefiles change |
| 2 | DL/ubuntu/X.filename | LocalFilename, or the URL's last component | the makefiles change (or X.url, for URLProgram systems) |
| 3 | DL/ubuntu/noble-server-cloudimg-amd64.img | image-garden download-with-sha256sums | missing, or failing its check |
| 4 | DL/ubuntu/X.qcow2, a link to step 3 | ln -sfn and mv -fT | X.url or X.filename is newer than the image |
| 5 | X.user-data, X.meta-data | the cloud-init templates | the makefiles, or .image-garden.mk, change |
| 6 | X.seed.iso | xorriso -as genisoimage -volid cidata | step 5 is remade |
| 7 | efi-code.x86_64.img, efi-vars.x86_64.img | cp from the EDK2 firmware | the source firmware is newer |
| 8 | X.efi-code.qcow2, X.efi-vars.qcow2 | qemu-img convert | step 7 is remade |
| 9 | X.qcow2 and X.qcow2.log | qemu-img create -b on step 4, then the provisioning boot | steps 4, 6 or 8 are newer |
| 10 | X.run | the launcher macro | the 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
| Banner | Step |
|---|---|
| Resolve URL for X | 1 |
| Resolve local filename for X | 2 |
| Download and verify base image for X | 3 and 4 |
| Generate cloud-init user-data for X, Generate cloud-init meta-data for X | 5 |
| Create cloud-init seed ISO X.seed.iso | 6 |
| Prepare writable qcow2 for X | 9, the overlay |
| Provision X | 9, the boot |
| Generate launcher script for X | 10 |
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.imgand so on). - Ubuntu Core downloads an
.img.xzand converts it to qcow2 in the cache before the link is made; see Ubuntu Core. - A named instance
BASE@NAME.ARCHhas its own steps 5, 6, 8, 9 and 10 on the base system's link; see named instances.
Special targets
| Target | Where | Effect |
|---|---|---|
.DELETE_ON_ERROR: | 000-garden.mk:7 | a target whose recipe fails is deleted |
.PRECIOUS: DL/GROUP/X.qcow2 | rulegen.py:494-496 | the cache link is kept when make is interrupted |
.PRECIOUS: %.qcow2 %.img | 010-qemu.mk:334 | files made by the convert pattern rules are kept; the explicit X.qcow2 overlay is not covered (derived) |
X.run with the disk after the bar | rulegen.py:594-594 | the disk and firmware are order-only prerequisites of the launcher |
Roads from here
RUNTIME · make rules and the CLI
- Downloading and checking images — how step three fetches, resumes and checks the image
- The overlay and the provisioning boot — step nine, the overlay and its provisioning boot
- Where image-garden keeps its files — where each of the ten files lives
- image-garden make and the other commands — dry runs, banners and the other commands
FIRST BOOT · cloud-init changes
- Provisioning runs once — what cloud-init does with the seed in that boot
BUILD TIME · data and rules
- What rulegen.py emits — for contributors, how these rules are generated for each system