How image-garden.mk is put together
three parts, one file for contributors
The top-level Makefile joins data/000-systems.mk, the sorted mk/*.mk and the sorted data/050-*.gen.mk into one image-garden.mk, installed where the image-garden script looks for it; the metadata leads so that define-instance works, and the sort order decides which assignment wins.
On the map: build time
▶ Watch this deck — 7 scenes, ~6 min
Worth seeing first
- From a system's name to a running VM — the path from an INI section to a running VM
01 One makefile, built from many
image-garden make runs make -f PREFIX/include/image-garden.mk. The file is built by the top-level Makefile from mk/*.mk, data/*.ini and rulegen.py, and installed with make install.
When you type image-garden make, the script runs GNU make on a single makefile, image-garden.mk, from the include directory of the prefix it was installed to. Every rule for every system is in that one file. The source tree doesn't contain it. It has fourteen makefiles written by hand in the mk directory, thirteen INI files in data, and rulegen.py. Running plain make at the top of the tree joins them into one file, about fifteen thousand nine hundred lines long, and make install copies it into place. This deck shows how the parts are joined, why their order matters, and what happens when one of them fails.
Details and sources
Details
- The script sets
GARDEN_INCLUDE=@INCLUDEDIR@, whichmake installfills in with$(includedir), andimage-garden makerunsmake --warn-undefined-variables GARDEN_ITSELF=… GARDEN_PROJECT_DIR=… -f "$GARDEN_INCLUDE"/image-garden.mk -C DIR "$@"(image-garden:10-12, image-garden:982-993). - The default goal of the top-level Makefile is
all:: image-garden.mk;prefixdefaults to/usr/localandincludedirto$(prefix)/include(Makefile:6-21). mk/holds 14.mkfiles (and a README),data/13 INI files (and a README). The joined file had 15,889 lines when built in a scratch copy of the pinned commit: 847 of metadata, 1,907 written by hand and 13,135 generated.- mk/README.md:5-10: the files "are all concatenated and installed as
image-garden.mk" to/usr/local/includeor/usr/include. make installreplaces@PREFIX@,@INCLUDEDIR@and@DOCDIR@in the installed script (Makefile:33-38). Run from the source tree, the script still has the placeholder, notices it, and readsimage-garden.mkfrom its own directory, the top of the tree (image-garden:13-19).
Read more
- GNU make underneath: what the command passes to make.
- Three ways in: the snap, the container and a source build.
02 Three parts, one cat
cat data/000-systems.mk $(sort mk/*.mk) $(sort data/050-*.gen.mk) >image-garden.mk. Each rule file depends on its INI file and on rulegen.py; the metadata depends on all of them.
The recipe that builds it is a single cat. First comes a metadata file that lists every system, with its group, release, architecture and boot type. Then the hand-written makefiles from mk, sorted by name: settings and helpers, the QEMU commands for each architecture, named instances, the rules written by hand, and last, the small file that pulls in your project's own makefile. Then the generated rule files, one per INI file, sorted too. The Makefile knows what each part is made from. Change an INI file, and its rule file and the metadata are made again. Change rulegen.py, and every one of them is. All of them are build output, which git ignores.
Details and sources
Details
image-garden.mk: $(wildcard mk/*.mk) $(foreach n,$(wildcard data/*.ini),data/050-$(basename $(notdir $n)).gen.mk) data/000-systems.mkwith the recipecat data/000-systems.mk $(sort $(filter mk/%.mk,$^)) $(sort $(filter data/050-%.gen.mk,$^)) >$@, thentouch --reference=the newest prerequisite, so the file gets the time of its newest part rather than the time it was joined (Makefile:48-50).data/050-%.gen.mk: rulegen.py data/%.ini(Makefile:57-58);data/000-systems.mkdepends on every INI file and on rulegen.py (Makefile:60-64).- The order on the slide is the one
make image-garden.mkprinted in a scratch copy of the tag. The six per-architecture files are010-qemu-aarch64,-loongarch64,-ppc64,-riscv64,-s390xand-x86_64. mk/999-local.mkis one line:-include $(GARDEN_PROJECT_DIR)/.image-garden.mk(999-local.mk:4-5).data/*.mkandimage-garden.mkare in .gitignore:16-17;make cleanremoves all three kinds (Makefile:23-27).
Read more
- What rulegen.py emits: the generated part.
- Rules written by hand: the
mk/050-*files. - Where the file goes and when it is read:
.image-garden.mk.
03 Why the metadata comes first
rulegen.py --systems-meta data/000-systems.mk writes _NAME_group, _group_upper, _release, _arch and _boot. define-instance in .image-garden.mk reads them before the generated rules are read.
Why does the metadata come first, before anything else? Because of your project's makefile. It's included at the end of the hand-written part, before make has read a single generated rule. And that's where you'd call define-instance, to make, say, a web server instance of ubuntu-cloud-24.04.x86_64. make runs that macro on the spot, and it needs the base system's group, release and boot type right then. So the Makefile runs rulegen.py a second time over every INI file, with the systems-meta option, and collects five variables per system into the file that leads. Ubuntu Core has no INI file, so it has no entry there.
Details and sources
Details
data/000-systems.mkis removed, then built by running./rulegen.py --systems-meta $@ $$f >/dev/nullfor each INI file in sorted order (Makefile:60-64). For each system rulegen.py appends_NAME_group,_NAME_group_upper,_NAME_release,_NAME_archand_NAME_bootwith:=(rulegen.py:824-833). It is 847 lines for 139 systems.- The project file is included by the last hand-written makefile (999-local.mk:4-5), and the generated rule files are joined after it.
define-instanceis used as$(eval $(call define-instance,BASE,NAME)); it tells a name with an architecture from one without by asking whether_BASE_groupis defined, then reads the group, upper-case group, release, boot type and architecture of the base from these variables; the architecture picks the QEMU rules, so a base named.ppc64elgets the ppc64 ones (020-instances.mk:4-19, 020-instances.mk:29-56).- Ubuntu Core's systems are added to
GARDEN_SYSTEMSby 050-ubuntu-core.mk:4-16 but get no metadata. The README says so: instances can be made of the systems indata/*.ini, "which are all but Ubuntu Core";define-instancewith an Ubuntu Core system lists the instance inlist-systems, but make has no rule for it (README.md:976-979, 020-instances.mk:9-10).
Read more
- Named instances, where else the boot type is read.
- Rules written by hand: what Ubuntu Core gives up by not being in an INI file.
04 The sort order decides
$(sort) is byte order: 010-qemu-x86_64.mk before 010-qemu.mk, which sets the host architecture's SMP to 4; 050-ubuntu.mk after 010-qemu.mk, so its EXTRA_CLOUD_INIT_APT_CONFIG wins; 050.gentoo.mk after the 050- files.
Sorting by name sounds harmless, but in make, order decides. A plain assignment that comes later replaces an earlier one. And make's sort compares bytes, so a dash comes before a dot. That puts the six architecture files before the common QEMU file, and it's how your machine's own architecture gets four CPUs, overriding the one its file sets. The Ubuntu file comes after the common one too, so its apt hook for old releases replaces the empty default. Gentoo's file has a dot where the others have a dash, so it sorts after them. When you add a file, pick its number for what it has to come after.
Details and sources
Details
- The recipe sorts the
mk/files and the generated files with make's$(sort)(Makefile:48-50), which orders words lexically by byte;-is 0x2D and.is 0x2E. The ordermake image-garden.mkprinted in a scratch copy of the pinned commit:010-qemu-aarch64…010-qemu-x86_64, then010-qemu.mk;050-amazonlinux-2.mk,050-ubuntu-core.mk,050-ubuntu.mk,050.gentoo.mk,999-local.mk. QEMU_SMP_X86_64 = 1(010-qemu-x86_64.mk:7-7);QEMU_SMP_$(shell echo $(GARDEN_HOST_ARCH) | tr a-z- A-Z_) = 4(010-qemu.mk:5-6), whereGARDEN_HOST_ARCHisuname -mwithppc64lemapped toppc64(000-garden.mk:16). Both are recursive (=) assignments; the last one read wins, and a project's.image-garden.mk, read later still, can set its own.EXTRA_CLOUD_INIT_APT_CONFIG =(010-qemu.mk:47-47), called by the base template (010-qemu.mk:198-198); redefined to callUBUNTU_OLD_RELEASES_APT_CONFIGin 050-ubuntu.mk:26-28. Were the files the other way round, the empty assignment would win and old Ubuntu releases would lose their apt block (derived).mk/050.gentoo.mkonly definesGENTOO_CLOUD_INIT_USER_DATA_TEMPLATE(050.gentoo.mk:4-8), so its place in the order changes nothing.- Templates, macros and target-specific variables are expanded when they are used, so for them the order matters only between two definitions of the same name (derived from make's rules for recursive variables).
- The README gives every architecture "
4native,1cross-arch", which is what this order produces, a ppc64le host included (README.md:389-396, README.md:890-895).
Read more
- How the default is set: the SMP example in full.
- Old Ubuntu releases: the apt block.
- Hooks in .image-garden.mk: how a project replaces the same hook.
05 Installed where the script looks
make install puts image-garden.mk in $(includedir) and writes the prefix into the script. The snap uses prefix=/usr and a layout for /usr/include/image-garden.mk; the container installs to /usr/local; an uninstalled script reads the file next to itself.
Every way of installing image-garden puts the file where the script will look for it. make install copies it into the include directory and writes the prefix into the installed script, /usr/local unless you say otherwise. The snap builds with the prefix set to /usr, and a layout makes its copy appear at /usr/include inside the snap. The container runs the same make install, into /usr/local. And if you run the script straight from a source checkout, it notices the prefix was never filled in and reads image-garden.mk from its own directory. So after you edit anything in mk or data, run make again.
Details and sources
Details
make installdepends onimage-garden.mk, installs the script to$(bindir)and runssedon the installed copy to write in$(prefix),$(includedir)and$(datarootdir)/doc/image-garden, and installsimage-garden.mkto$(includedir), by default/usr/local/include; a differentincludedirordatarootdiris honoured (Makefile:6-14, Makefile:29-46).- The script:
GARDEN_INCLUDE=@INCLUDEDIR@; when the prefix is still the placeholder,GARDEN_INCLUDEbecomes the script's own directory (image-garden:10-19). - The snap's image-garden part passes
prefix=/usrto make (snapcraft.yaml:301-303), and its layout binds/usr/include/image-garden.mkto$SNAP/usr/include/image-garden.mk(snapcraft.yaml:250-252). - The container copies the tree to
/src/image-gardenand runsmake,make checkandmake installthere (Dockerfile:69-71). image-garden.mklists themk/*.mkfiles, the generated rule files and the metadata as prerequisites, somakein the tree rebuilds it after an edit; an installed copy is replaced only bymake install(derived).
Read more
06 When a part fails
A failed ./rulegen.py data/gentoo.ini >data/050-gentoo.gen.mk leaves an empty file, and make deletes it: the top-level Makefile has .DELETE_ON_ERROR. Every later make fails the same way until the INI file is fixed.
Say you mistype a boot type in Gentoo's INI file and run make. rulegen.py stops with an error that names the file, the section and the values you can use, and make stops too. But the shell had already created Gentoo's rule file, empty, before rulegen.py ran. The top-level Makefile tells make to delete any target whose recipe fails, so make removes that file and says so. Run make again without a fix and you get the same error, not a quiet image-garden.mk without Gentoo. Fix the line, run make, and the rule file, the metadata and the joined file are all made again.
Details and sources
Details
- Run in a scratch copy of the pinned commit with
Boot=uefiin the first section ofdata/gentoo.ini:makestopped withdata/gentoo.ini: error: Image 'gentoo-cloud.x86_64' has Boot='uefi', use one of platform, efi, bios, thenmake: *** [Makefile:58: data/050-gentoo.gen.mk] Error 1andmake: *** Deleting file 'data/050-gentoo.gen.mk'. A secondmakeprinted the same three lines. After restoringBoot=efi,makebuilt the rule file,data/000-systems.mkandimage-garden.mkwith Gentoo's systems. - The rule file is written by the shell redirection
>$@before rulegen.py runs (Makefile:57-58); the metadata recipe starts withrm -f $@and appends file by file (Makefile:60-64)..DELETE_ON_ERRORin the top-level Makefile, "so that the next make does not use it", makes make delete either of them when its recipe fails (Makefile:16-18). image-garden.mk sets the same for the rules it runs at run time (000-garden.mk:4-7). - The message names the section and the values the architecture accepts (rulegen.py:300-333); it is printed as
FILE: error: MESSAGEwithout a traceback (rulegen.py:753-757). - An
image-garden.mkalready built from the earlier, good INI file is not touched by the failed run; it stays out of date, so the nextmaketries again (derived from the rule at Makefile:48-50). make cleanremovesimage-garden.mk,data/050-*.gen.mkanddata/000-systems.mk(Makefile:23-27); it is not needed after such an error.
Read more
- Check everything, then print: rulegen.py itself prints nothing for a bad file.
- When Boot is wrong or missing: the message on the slide.
07 Where to go from here
Next: rulegen.py, the hand-written rules, .image-garden.mk, the SMP default, image-garden make, and the source build.
So image-garden.mk is three parts joined in a fixed order: the metadata, the hand-written makefiles, and the generated rules. The rulegen deck explains the generated part, and the hand-written rules deck the files that stand in for it, such as Ubuntu Core. Your project's own makefile slots in between, and the deck on extending the first boot shows what to put there. The architectures deck has the CPU count example in full. The command line deck shows how image-garden make calls make, and the source build deck how to install what you've built.
Details and sources
Details
- The recipe in one line:
cat data/000-systems.mk $(sort mk/*.mk) $(sort data/050-*.gen.mk) >image-garden.mk(Makefile:48-50).
Read more
Basis of the statements on this page
Read in the top-level Makefile, rulegen.py, mk/*.mk, mk/README.md, the image-garden script, snap/snapcraft.yaml, the Dockerfile and .gitignore of image-garden at the pinned commit ("code"). The order of the parts, the line counts and the runs after an error come from make image-garden.mk in a scratch copy of that commit ("run"). What would happen with another order, and when an installed copy is replaced, are reasoned from make's rules ("derived").
The order of image-garden.mk
| # | File | Lines | What it holds |
|---|---|---|---|
| 1 | data/000-systems.mk | 847 | five variables per system from the INI files |
| 2 | mk/000-garden.mk | 87 | .DELETE_ON_ERROR, cache directories, CURL, XORRISO, log banners, GARDEN_SYMLINK, help, list-systems |
| 3 | mk/010-qemu-aarch64.mk | 218 | QEMU command lines, run scripts and firmware for aarch64 |
| 4 | mk/010-qemu-loongarch64.mk | 119 | the same for loongarch64 |
| 5 | mk/010-qemu-ppc64.mk | 72 | the same for ppc64 |
| 6 | mk/010-qemu-riscv64.mk | 121 | the same for riscv64 |
| 7 | mk/010-qemu-s390x.mk | 72 | the same for s390x |
| 8 | mk/010-qemu-x86_64.mk | 334 | the same for x86_64, with Secure Boot and swtpm |
| 9 | mk/010-qemu.mk | 347 | common QEMU settings, pkgproxy, the cloud-init templates and picker, the seed ISO, the locked unpack and convert |
| 10 | mk/020-instances.mk | 157 | define-instance |
| 11 | mk/050-amazonlinux-2.mk | 11 | Amazon Linux 2's template and the aarch64 CPU |
| 12 | mk/050-ubuntu-core.mk | 328 | every Ubuntu Core system |
| 13 | mk/050-ubuntu.mk | 28 | the apt block for old Ubuntu releases |
| 14 | mk/050.gentoo.mk | 8 | Gentoo's template |
| 15 | mk/999-local.mk | 5 | -include $(GARDEN_PROJECT_DIR)/.image-garden.mk |
| 16-28 | data/050-almalinux.gen.mk … data/050-ubuntu.gen.mk | 13,135 | the generated rules, one file per INI file |
Total: 15,889 lines. The mk/ files are sorted with make's $(sort), byte by byte, so 010-qemu-*.mk precede 010-qemu.mk and 050.gentoo.mk follows the 050- files (Makefile:48-50).
Targets of the top-level Makefile
| Target | What it does |
|---|---|
all (default) | builds image-garden.mk |
install | installs image-garden, image-garden.mk, the manual page and the documentation under DESTDIR and prefix (or bindir, includedir, datarootdir, man1dir), and writes the prefix, the include directory and the documentation directory into the script |
clean | removes image-garden.mk, data/050-*.gen.mk and data/000-systems.mk |
check | check-sh, check-py, check-rulegen, check-dl-pkgproxy, check-allocate, check-rebase, check-dl-unpack-lock, check-pkgproxy-guest-shell |
fmt | shfmt and black |
dist | image-garden-VERSION.tar.gz with the sources, not the generated files |
Source: Makefile:16-141.
Where each install puts it
| Install | Prefix | image-garden.mk | Source |
|---|---|---|---|
make install | /usr/local, or prefix= | $(includedir)/image-garden.mk, by default PREFIX/include | Makefile:6-46 |
| the snap | /usr | /usr/include/image-garden.mk, bound by a layout | snapcraft.yaml:250-252, :301-303 |
| the container | /usr/local | /usr/local/include/image-garden.mk | Dockerfile:69-71 |
| not installed | none | image-garden.mk next to the script | image-garden:13-19 |
After an error
A failed rulegen.py run leaves an empty data/050-X.gen.mk, and a failed metadata loop a partial data/000-systems.mk; the top-level Makefile has .DELETE_ON_ERROR, so make deletes the file and prints make: *** Deleting file '…' (Makefile:16-18). Every later make fails the same way until the INI file is fixed (run); make clean is not needed.
Roads from here
ARCHITECTURES · machines and firmware
- Six architectures, six QEMU machines — the SMP default, the order rule in full
RUNTIME · make rules and the CLI
- image-garden make and the other commands — how image-garden make runs make on the joined file
FIRST BOOT · cloud-init changes
- Changing what cloud-init does — what to put in .image-garden.mk, read between the two parts
NATIVE · packages
- Installing from source — building and installing image-garden from source
BUILD TIME · data and rules
- What rulegen.py emits — the generated part, what rulegen.py writes for each section
- Rules written by hand — the hand-written systems and quirks in mk/050-*