Merge pull request #3482 from jandubois/user-templates

Finish $LIMA_TEMPLATES_PATH, add $LIMA_HOME/_templates

Author: jandubois

cmd/limactl/start.go

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

pkg/templatestore/templatestore.go

@@ -4,15 +4,18 @@
 package templatestore
 
 import (
+	"cmp"
 	"errors"
 	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"unicode"
 
 	securejoin "github.com/cyphar/filepath-securejoin"
+	"github.com/lima-vm/lima/pkg/store/dirnames"
 	"github.com/lima-vm/lima/pkg/usrlocalsharelima"
 )
 
@@ -21,25 +24,37 @@ type Template struct {
 	Location string `json:"location"`
 }
 
-func Read(name string) ([]byte, error) {
-	var pathList []string
+func TemplatesPaths() ([]string, error) {
 	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")}
+		return strings.Split(tmplPath, string(filepath.ListSeparator)), nil
+	}
+	limaDir, err := dirnames.LimaDir()
+	if err != nil {
+		return nil, err
+	}
+	shareDir, err := usrlocalsharelima.Dir()
+	if err != nil {
+		return nil, err
+	}
+	return []string{
+		filepath.Join(limaDir, "_templates"),
+		filepath.Join(shareDir, "templates"),
+	}, nil
+}
+
+func Read(name string) ([]byte, error) {
+	paths, err := TemplatesPaths()
+	if err != nil {
+		return nil, err
 	}
 	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"
 	}
-	for _, path := range pathList {
-		filePath, err := securejoin.SecureJoin(path, name)
+	for _, templatesDir := range paths {
+		filePath, err := securejoin.SecureJoin(templatesDir, name)
 		if err != nil {
 			return nil, err
 		}
@@ -53,31 +68,39 @@ func Read(name string) ([]byte, error) {
 const Default = "default"
 
 func Templates() ([]Template, error) {
-	usrlocalsharelimaDir, err := usrlocalsharelima.Dir()
+	paths, err := TemplatesPaths()
 	if err != nil {
 		return nil, err
 	}
-	templatesDir := filepath.Join(usrlocalsharelimaDir, "templates")
 
-	var res []Template
-	walkDirFn := func(p string, _ fs.DirEntry, err error) error {
-		if err != nil {
-			return err
+	templates := make(map[string]string)
+	for _, templatesDir := range paths {
+		if _, err := os.Stat(templatesDir); os.IsNotExist(err) {
+			continue
 		}
-		base := filepath.Base(p)
-		if strings.HasPrefix(base, ".") || !strings.HasSuffix(base, ".yaml") {
+		walkDirFn := func(p string, _ fs.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+			base := filepath.Base(p)
+			if strings.HasPrefix(base, ".") || !strings.HasSuffix(base, ".yaml") {
+				return nil
+			}
+			// Name is like "default", "debian", "deprecated/centos-7", ...
+			name := strings.TrimSuffix(strings.TrimPrefix(p, templatesDir+"/"), ".yaml")
+			if _, ok := templates[name]; !ok {
+				templates[name] = p
+			}
 			return nil
 		}
-		x := Template{
-			// Name is like "default", "debian", "deprecated/centos-7", ...
-			Name:     strings.TrimSuffix(strings.TrimPrefix(p, templatesDir+"/"), ".yaml"),
-			Location: p,
+		if err = filepath.WalkDir(templatesDir, walkDirFn); err != nil {
+			return nil, err
 		}
-		res = append(res, x)
-		return nil
 	}
-	if err = filepath.WalkDir(templatesDir, walkDirFn); err != nil {
-		return nil, err
+	var res []Template
+	for name, loc := range templates {
+		res = append(res, Template{Name: name, Location: loc})
 	}
+	slices.SortFunc(res, func(i, j Template) int { return cmp.Compare(i.Name, j.Name) })
 	return res, nil
 }

website/content/en/docs/config/environment-variables.md

@@ -30,7 +30,7 @@ This page documents the environment variables used in Lima.
 ### `LIMA_TEMPLATES_PATH`
 
 - **Description**: Specifies the directories used to resolve `template://` URLs.
-- **Default**: `/usr/local/share/lima/templates`
+- **Default**: `$LIMA_HOME/_templates:/usr/local/share/lima/templates`
 - **Usage**:
   ```sh
   export LIMA_TEMPLATES_PATH="$HOME/.config/lima/templates:/usr/local/share/lima/templates"

website/content/en/docs/dev/internals.md

@@ -107,6 +107,12 @@ When using `vmType: vz` (Virtualization.framework), on boot, any qcow2 (default)
 
 `ls` will also only show the full/virtual size of the disks. To see the allocated space, `du -h disk_path` or `qemu-img info disk_path` can be used instead. See [#1405](https://github.com/lima-vm/lima/pull/1405) for more details.
 
+## Templates directory (`${LIMA_HOME}/_templates`)
+
+The templates directory can store additional template files that can be referenced with the `template://` schema.
+
+If the template directory exists (and `$LIMA_TEMPLATES_PATH` is not set), then this directory will be searched before the `/usr/local/share/lima/templates` default directory that contains all the templates bundled with Lima itself.
+
 ## Lima cache directory (`~/Library/Caches/lima`)
 
 Currently hard-coded to `~/Library/Caches/lima` on macOS.