Merge pull request #3453 from jandubois/image-templates

Refactor images lists and default mounts into base templates

Author: AkihiroSuda

.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"