Refactor images lists and default mounts into base templates

.github/workflows/test.yml

@@ -196,7 +196,8 @@ jobs:
     - name: Validate jsonschema
       run: make schema-limayaml.json
     - name: Validate templates
-      run: find -L templates -name '*.yaml' | xargs limactl validate
+      # Can't validate base templates in `_default` because they have no images
+      run: find -L templates -name '*.yaml' ! -path '*/_default/*' | xargs limactl validate
     - name: Install test dependencies
       # QEMU:      required by Lima itself
       # bash:      required by test-templates.sh (OS version of bash is too old)
@@ -208,7 +209,7 @@ jobs:
       run: echo "LIMACTL_CREATE_ARGS=${LIMACTL_CREATE_ARGS} --vm-type=qemu" >>$GITHUB_ENV
     - name: "Inject `no_timer_check` to kernel cmdline"
       # workaround to https://github.com/lima-vm/lima/issues/84
-      run: ./hack/inject-cmdline-to-template.sh templates/default.yaml no_timer_check
+      run: ./hack/inject-cmdline-to-template.sh templates/_images/ubuntu.yaml no_timer_check
     - name: Cache image used by default.yaml
       uses: ./.github/actions/setup_cache_for_template
       with:
@@ -353,7 +354,7 @@ jobs:
     steps:
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       with:
-        fetch-depth: 1
+        fetch-depth: 0
     - uses: actions/setup-go@0aaccfd150d50ccaeb58ebd88d36e91967a5f35b  # v5.4.0
       with:
         go-version: 1.24.x
@@ -365,7 +366,7 @@ jobs:
       run: echo "LIMACTL_CREATE_ARGS=${LIMACTL_CREATE_ARGS} --vm-type=qemu --network=lima:shared" >>$GITHUB_ENV
     - name: "Inject `no_timer_check` to kernel cmdline"
       # workaround to https://github.com/lima-vm/lima/issues/84
-      run: ./hack/inject-cmdline-to-template.sh templates/default.yaml no_timer_check
+      run: ./hack/inject-cmdline-to-template.sh templates/_images/ubuntu.yaml no_timer_check
     - name: Cache image used by default .yaml
       uses: ./.github/actions/setup_cache_for_template
       with:
@@ -408,6 +409,7 @@ jobs:
     steps:
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       with:
+        # To avoid "failed to load YAML file \"templates/experimental/riscv64.yaml\": can't parse builtin Lima version \"3f3a6f6\": 3f3a6f6 is not in dotted-tri format"
         fetch-depth: 0
     - name: Fetch homebrew-core commit messages
       uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
@@ -452,7 +454,7 @@ jobs:
     steps:
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       with:
-        fetch-depth: 1
+        fetch-depth: 0
     - uses: actions/setup-go@0aaccfd150d50ccaeb58ebd88d36e91967a5f35b  # v5.4.0
       with:
         go-version: 1.24.x
@@ -487,7 +489,7 @@ jobs:
     steps:
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       with:
-        fetch-depth: 1
+        fetch-depth: 0
     - uses: actions/setup-go@0aaccfd150d50ccaeb58ebd88d36e91967a5f35b  # v5.4.0
       with:
         go-version: 1.24.x

.gitignore

@@ -1,5 +1,6 @@
 _output/
 _artifacts/
 lima.REJECTED.yaml
+default-template.yaml
 schema-limayaml.json
 .config

.ls-lint.yml

@@ -19,6 +19,10 @@ ls:
   docs:
     .md: kebab-case
 
+  templates:
+    # _default and _images have leading underscores
+    .dir: lowercase
+
   website/content:
     .dir: lowercase
 

Makefile

@@ -419,14 +419,19 @@ ifeq ($(native_compiling),true)
 endif
 
 ################################################################################
-schema-limayaml.json: _output/bin/limactl$(exe)
+default-template.yaml: _output/bin/limactl$(exe)
 ifeq ($(native_compiling),true)
-	$< generate-jsonschema --schemafile $@ templates/default.yaml
+	$< tmpl copy --embed-all templates/default.yaml $@
+endif
+
+schema-limayaml.json: _output/bin/limactl$(exe) default-template.yaml
+ifeq ($(native_compiling),true)
+	$< generate-jsonschema --schemafile $@ default-template.yaml
 endif
 
 .PHONY: check-jsonschema
-check-jsonschema: schema-limayaml.json
-	check-jsonschema --schemafile $< templates/default.yaml
+check-jsonschema: schema-limayaml.json default-template.yaml
+	check-jsonschema --schemafile schema-limayaml.json default-template.yaml
 
 ################################################################################
 .PHONY: diagrams

cmd/limactl/start.go

@@ -374,7 +374,10 @@ func createStartActionCommon(cmd *cobra.Command, _ []string) (exit bool, err err
 		if templates, err := templatestore.Templates(); err == nil {
 			w := cmd.OutOrStdout()
 			for _, f := range templates {
-				_, _ = fmt.Fprintln(w, f.Name)
+				// Don't show internal base templates like `_default/*` and `_images/*`.
+				if !strings.HasPrefix(f.Name, "_") {
+					_, _ = fmt.Fprintln(w, f.Name)
+				}
 			}
 			return true, nil
 		}

hack/common.inc.sh

@@ -29,3 +29,9 @@ _IPERF3=iperf3
 # https://github.com/lima-vm/socket_vmnet/issues/85
 [ "$(uname -s)" = "Darwin" ] && _IPERF3="iperf3-darwin"
 : "${IPERF3:=$_IPERF3}"
+
+# Setup LIMA_TEMPLATES_PATH because the templates are not installed, but reference base templates
+# via template://_images/* and template://_default/*.
+templates_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../templates" && pwd)"
+: "${LIMA_TEMPLATES_PATH:-$templates_dir}"
+export LIMA_TEMPLATES_PATH

hack/test-templates.sh

@@ -22,8 +22,8 @@ FILE="$(cd "$(dirname "$1")" && pwd)/$(basename "$1")"
 NAME="$(basename -s .yaml "$FILE")"
 OS_HOST="$(uname -o)"
 
-# On Windows $HOME of the bash runner, %USERPROFILE% of the host machine and mpunting point in the guest machine
-# are all different folders. This will handle path differences, when values are expilictly set.
+# On Windows $HOME of the bash runner, %USERPROFILE% of the host machine and mounting point in the guest machine
+# are all different folders. This will handle path differences, when values are explicitly set.
 HOME_HOST=${HOME_HOST:-$HOME}
 HOME_GUEST=${HOME_GUEST:-$HOME}
 FILE_HOST=$FILE

pkg/limayaml/limayaml_test.go

@@ -37,6 +37,8 @@ func TestDefaultYAML(t *testing.T) {
 	assert.NilError(t, err)
 	y.Images = nil                // remove default images
 	y.Mounts = nil                // remove default mounts
+	y.Base = nil                  // remove default base templates
+	y.MinimumLimaVersion = nil    // remove minimum Lima version
 	y.MountTypesUnsupported = nil // remove default workaround for kernel 6.9-6.11
 	t.Log(dumpJSON(t, y))
 	b, err := Marshal(&y, false)

pkg/limayaml/validate_test.go

@@ -4,8 +4,6 @@
 package limayaml
 
 import (
-	"os"
-	"runtime"
 	"testing"
 
 	"gotest.tools/v3/assert"
@@ -18,22 +16,6 @@ func TestValidateEmpty(t *testing.T) {
 	assert.Error(t, err, "field `images` must be set")
 }
 
-// Note: can't embed symbolic links, use "os"
-
-func TestValidateDefault(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		// FIXME: `assertion failed: error is not nil: field `mounts[1].location` must be an absolute path, got "/tmp/lima"`
-		t.Skip("Skipping on windows")
-	}
-
-	bytes, err := os.ReadFile("default.yaml")
-	assert.NilError(t, err)
-	y, err := Load(bytes, "default.yaml")
-	assert.NilError(t, err)
-	err = Validate(y, true)
-	assert.NilError(t, err)
-}
-
 func TestValidateProbes(t *testing.T) {
 	images := `images: [{"location": "/"}]`
 	validProbe := `probes: [{"script": "#!foo"}]`

pkg/templatestore/templatestore.go

@@ -4,6 +4,8 @@
 package templatestore
 
 import (
+	"errors"
+	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
@@ -20,21 +22,32 @@ type Template struct {
 }
 
 func Read(name string) ([]byte, error) {
-	dir, err := usrlocalsharelima.Dir()
-	if err != nil {
-		return nil, err
+	var pathList []string
+	if tmplPath := os.Getenv("LIMA_TEMPLATES_PATH"); tmplPath != "" {
+		pathList = strings.Split(tmplPath, string(filepath.ListSeparator))
+	} else {
+		dir, err := usrlocalsharelima.Dir()
+		if err != nil {
+			return nil, err
+		}
+		pathList = []string{filepath.Join(dir, "templates")}
 	}
 	ext := filepath.Ext(name)
 	// Append .yaml extension if name doesn't have an extension, or if it starts with a digit.
 	// So "docker.sh" would remain unchanged but "ubuntu-24.04" becomes "ubuntu-24.04.yaml".
 	if len(ext) < 2 || unicode.IsDigit(rune(ext[1])) {
 		name += ".yaml"
 	}
-	filePath, err := securejoin.SecureJoin(filepath.Join(dir, "templates"), name)
-	if err != nil {
-		return nil, err
+	for _, path := range pathList {
+		filePath, err := securejoin.SecureJoin(path, name)
+		if err != nil {
+			return nil, err
+		}
+		if b, err := os.ReadFile(filePath); !errors.Is(err, os.ErrNotExist) {
+			return b, err
+		}
 	}
-	return os.ReadFile(filePath)
+	return nil, fmt.Errorf("template %q not found", name)
 }
 
 const Default = "default"

templates/_default/mounts.yaml

@@ -0,0 +1,4 @@
+mounts:
+- location: "~"
+- location: "/tmp/lima"
+  writable: true

templates/_images/almalinux-8.yaml

@@ -0,0 +1,33 @@
+# NOTE: EL8-based distros are known not to work on M1 chips: https://github.com/lima-vm/lima/issues/841
+# EL9-based distros are known to work.
+images:
+- location: https://repo.almalinux.org/almalinux/8.10/cloud/x86_64/images/AlmaLinux-8-GenericCloud-8.10-20240819.x86_64.qcow2
+  arch: x86_64
+  digest: sha256:669bd580dcef5491d4dfd5724d252cce7cde1b2b33a3ca951e688d71386875e3
+
+- location: https://repo.almalinux.org/almalinux/8.10/cloud/aarch64/images/AlmaLinux-8-GenericCloud-8.10-20240819.aarch64.qcow2
+  arch: aarch64
+  digest: sha256:cec6736cbc562d06895e218b6f022621343c553bfa79192ca491381b4636c7b8
+
+- location: https://repo.almalinux.org/almalinux/8.10/cloud/s390x/images/AlmaLinux-8-GenericCloud-8.10-20240819.s390x.qcow2
+  arch: s390x
+  digest: sha256:7f8866a4247ad57c81f5d2c5a0fa64940691f9df1e858a1510d34a0de008eb16
+
+# Fallback to the latest release image.
+# Hint: run `limactl prune` to invalidate the cache
+
+- location: https://repo.almalinux.org/almalinux/8/cloud/x86_64/images/AlmaLinux-8-GenericCloud-latest.x86_64.qcow2
+  arch: x86_64
+
+- location: https://repo.almalinux.org/almalinux/8/cloud/aarch64/images/AlmaLinux-8-GenericCloud-latest.aarch64.qcow2
+  arch: aarch64
+
+- location: https://repo.almalinux.org/almalinux/8/cloud/s390x/images/AlmaLinux-8-GenericCloud-latest.s390x.qcow2
+  arch: s390x
+
+mountTypesUnsupported: [9p]
+
+cpuType:
+  # Workaround for "vmx_write_mem: mmu_gva_to_gpa XXXXXXXXXXXXXXXX failed" on Intel Mac
+  # https://bugs.launchpad.net/qemu/+bug/1838390
+  x86_64: Haswell-v4

templates/_images/almalinux-9.yaml

@@ -0,0 +1,26 @@
+images:
+- location: https://repo.almalinux.org/almalinux/9.5/cloud/x86_64/images/AlmaLinux-9-GenericCloud-9.5-20241120.x86_64.qcow2
+  arch: x86_64
+  digest: sha256:abddf01589d46c841f718cec239392924a03b34c4fe84929af5d543c50e37e37
+
+- location: https://repo.almalinux.org/almalinux/9.5/cloud/aarch64/images/AlmaLinux-9-GenericCloud-9.5-20241120.aarch64.qcow2
+  arch: aarch64
+  digest: sha256:5ede4affaad0a997a2b642f1628b6268bd8eba775f281346b75be3ed20ec369e
+
+- location: https://repo.almalinux.org/almalinux/9.5/cloud/s390x/images/AlmaLinux-9-GenericCloud-9.5-20241120.s390x.qcow2
+  arch: s390x
+  digest: sha256:9948ea1c5ee1c6497bde5cec18c71c5f9e50861af4c0f1400c1af504eee2b995
+
+# Fallback to the latest release image.
+# Hint: run `limactl prune` to invalidate the cache
+
+- location: https://repo.almalinux.org/almalinux/9/cloud/x86_64/images/AlmaLinux-9-GenericCloud-latest.x86_64.qcow2
+  arch: x86_64
+
+- location: https://repo.almalinux.org/almalinux/9/cloud/aarch64/images/AlmaLinux-9-GenericCloud-latest.aarch64.qcow2
+  arch: aarch64
+
+- location: https://repo.almalinux.org/almalinux/9/cloud/s390x/images/AlmaLinux-9-GenericCloud-latest.s390x.qcow2
+  arch: s390x
+
+mountTypesUnsupported: [9p]

templates/_images/alpine-iso.yaml

@@ -0,0 +1,9 @@
+# Using the Alpine 3.20 aarch64 image with vmType=vz requires macOS Ventura 13.3 or later.
+images:
+- location: https://github.com/lima-vm/alpine-lima/releases/download/v0.2.41/alpine-lima-std-3.20.3-x86_64.iso
+  arch: x86_64
+  digest: sha512:949a353c1676bb406561d22c1b7f9db72fb0cc899c6c50166df3b38e392280a7e7b83f58643a309816d51a48317507c46c3e7e24e52fbc9f20fe817039306db1
+
+- location: https://github.com/lima-vm/alpine-lima/releases/download/v0.2.41/alpine-lima-std-3.20.3-aarch64.iso
+  arch: aarch64
+  digest: sha512:91ea119fea2bb638519792de2047303b26eaebcdace8df57b76373dc7b1cddcad77aaa9fed2d438fb02351b261783af3264d6bb2716519f8ba211a4b25d6f114

templates/_images/alpine.yaml

@@ -0,0 +1,8 @@
+images:
+- location: https://dl-cdn.alpinelinux.org/alpine/v3.21/releases/cloud/nocloud_alpine-3.21.2-x86_64-uefi-cloudinit-r0.qcow2
+  arch: x86_64
+  digest: sha512:1aaf22b4a584e69e228e6aa38a295159c0143d9ccebe7ad4928e92b414714066af3bfe5f9e0ca4d4d64a70ca9fea09033af90258a6f2344130d70b660151127a
+
+- location: https://dl-cdn.alpinelinux.org/alpine/v3.21/releases/cloud/nocloud_alpine-3.21.2-aarch64-uefi-cloudinit-r0.qcow2
+  arch: aarch64
+  digest: sha512:08d340126b222abae651a20aa63c3ee3dc601d703de7879d2a6bc1fe82a3664d058a2c55ad0cf8a874327f7535e3af8a9384ce438217d6f32200cad1462a5b32

templates/_images/archlinux.yaml

@@ -0,0 +1,16 @@
+images:
+# Try to use yyyyMMdd.REV image if available. Note that yyyyMMdd.REV will be removed after several months.
+
+- location: https://geo.mirror.pkgbuild.com/images/v20250315.322357/Arch-Linux-x86_64-cloudimg-20250315.322357.qcow2
+  arch: x86_64
+  digest: sha256:b162746f6e64064500901ecb61b76f3d2873fcd25bdab4aaa784758719a701c5
+
+- location: https://github.com/mcginty/arch-boxes-arm/releases/download/v20220323/Arch-Linux-aarch64-cloudimg-20220323.0.qcow2
+  arch: aarch64
+  digest: sha512:27524910bf41cb9b3223c8749c6e67fd2f2fdb8b70d40648708e64d6b03c0b4a01b3c5e72d51fefd3e0c3f58487dbb400a79ca378cde2da341a3a19873612be8
+
+# Fallback to the latest release image.
+# Hint: run `limactl prune` to invalidate the cache
+
+- location: https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-cloudimg.qcow2
+  arch: x86_64

templates/_images/centos-stream-10.yaml

@@ -0,0 +1,39 @@
+images:
+# Try to use release-yyyyMMdd image if available. Note that release-yyyyMMdd will be removed after several months.
+
+- location: https://cloud.centos.org/centos/10-stream/x86_64/images/CentOS-Stream-GenericCloud-10-20250317.0.x86_64.qcow2
+  arch: x86_64
+  digest: sha256:24578ef181b03ab577acaa885cbc24b1c91fbae613d50152796cbe6c2e004aab
+
+- location: https://cloud.centos.org/centos/10-stream/aarch64/images/CentOS-Stream-GenericCloud-10-20250317.0.aarch64.qcow2
+  arch: aarch64
+  digest: sha256:5cfd6199d9f9ada1e4e44113938981b2dce96ba3e9e670549e6e1c1a8e74f167
+
+- location: https://cloud.centos.org/centos/10-stream/s390x/images/CentOS-Stream-GenericCloud-10-20250317.0.s390x.qcow2
+  arch: s390x
+  digest: sha256:903b47d726fa9a892853cfb805d52a0bf75a7fc710169619bdaae7c3e3a00296
+
+# Fallback to the latest release image.
+# Hint: run `limactl prune` to invalidate the cache
+
+- location: https://cloud.centos.org/centos/10-stream/x86_64/images/CentOS-Stream-GenericCloud-10-latest.x86_64.qcow2
+  arch: x86_64
+
+- location: https://cloud.centos.org/centos/10-stream/aarch64/images/CentOS-Stream-GenericCloud-10-latest.aarch64.qcow2
+  arch: aarch64
+
+- location: https://cloud.centos.org/centos/10-stream/s390x/images/CentOS-Stream-GenericCloud-10-latest.s390x.qcow2
+  arch: s390x
+
+mountTypesUnsupported: [9p]
+
+firmware:
+  # CentOS Stream 10 still requires legacyBIOS
+  # https://issues.redhat.com/browse/CS-2672
+  legacyBIOS: true
+
+cpuType:
+  # When emulating Intel on ARM hosts, Lima uses the "qemu64" CPU by default (https://github.com/lima-vm/lima/pull/494).
+  # However, CentOS Stream 10 kernel reboots indefinitely due to lack of the support for x86_64-v3 instructions.
+  # This issue is tracked in <https://github.com/lima-vm/lima/issues/3063>.
+  x86_64: "Haswell-v4"