buildkit

Documentation

Overview

Package buildkit holds the pure Containerfile render/compute machinery that any build front-end (the charly host engine, an out-of-tree build plugin) can import — the SDK-library half of the "core is the kernel; every capability is a plugin" architecture. This file is the format/builder TEMPLATE render surface: cache-mount rendering, the shared template.FuncMap, the text/template driver, and the InstallContext constructor. It depends only on sdk/spec (the wire types) and sdk/kit (shell quoting) — never on charly core.

Index

• Constants
• Variables
• func BootstrapPackagesForBox(distro *spec.ResolvedDistro) []string
• func CandyStatus(c spec.CandyReader) string
• func CharlyBinaryUpToDate(binPath, srcDir string) (bool, error)
• func CopyFileBytes(src, dst string) error
• func DetectRemoteBuildRef(dir string, boxes []string) (string, bool)
• func HostPlatform() string
• func NewInstallContext(section map[string]any, cacheMounts []spec.CacheMount) *spec.InstallContext
• func NormalizeBoxArgs(boxes []string) []string
• func PkgName(s string) string
• func RenderBootstrapScript(builder *BuilderDef, ctx any) (string, error)
• func RenderPacstrapExtraConf(p *spec.Pacstrap) string
• func RenderRuntimePacmanConf(p *spec.Pacstrap) (string, error)
• func RenderSystemPackagesFragment(format string, phase spec.Phase, rawInstallContext map[string]any, ...) (string, error)
• func RenderTemplate(name, tmplStr string, ctx any) (string, error)
• func ResolveAllBox(cfg *spec.Config, calverTag string, dir string, opts ResolveOpts) (map[string]*ResolvedBox, error)
• func ResolveStageParallelism(override, jobsCap int) int
• func ResolveStatus(s string) string
• func RunPrivileged(p PrivilegedRun) error
• func StatusSeverity(s string) int
• func ToMapSlice(v any) []map[string]any
• func ToStringSlice(v any) []string
• func WorstStatus(a, b string) string
• type AggregatedCandyCaps
• type BuilderConfig
• type BuilderDef
• type BuilderMap
• type CacheMount
  • func OwnedCacheMount(dst string, uid, gid int) CacheMount
  • func SharedCacheMount(dst, sharing string) CacheMount
  • func (m CacheMount) String() string
• type DistroConfig
• type DistroDef
• type FormatDef
• type InitConfig
• type MergeConfig
• type PrivilegedRun
• type ResolveOpts
  • func (opts ResolveOpts) ShouldIncludeDisabled(name string) bool
• type ResolvedBox
  • func ResolveBox(cfg *spec.Config, name string, calverTag string, dir string, opts ResolveOpts) (*ResolvedBox, error)
• type ResolvedInit

Constants

const (
	StatusWorking = "working"
	StatusTesting = "testing"
	StatusBroken  = "broken"
)

Status rungs. The default (empty) is StatusTesting; StatusWorking is the most permissive (used as the box-status seed so the candy chain drives the rung).

const RootfsOutputFloor = 4 << 30

RootfsOutputFloor is the MinFreeBytes floor for a privileged rootfs build: the output is a gzipped rootfs tarball (typically 1-3 GiB for pacstrap/debootstrap), so require 4 GiB of free space on the staging + destination filesystems. A full disk used to fail cryptically inside the container ("gzip: stdout: No space left on device"). Shared by the OCI-image bootstrap (candy/plugin-build) and the VM-bootstrap engine (candy/plugin-vm) — one floor, R3.

const StageParallelismCapFallback = 4

StageParallelismCapFallback is the ceiling on the auto-computed inner-concurrency value (the knob the contract renamed from `podman_jobs` to `stage_parallelism`), used ONLY when `defaults.stage_parallelism_cap` is absent from project config. The operative ceiling is that key; this conservative constant just keeps configs that do not declare it on a safe value. The per-build override is `--stage-parallelism` / `CHARLY_STAGE_PARALLELISM`.

⚑ What the value now DRIVES changed with the builder: it was `podman build --jobs N` (the concurrent stages of one build), and it is now the BuildKit daemon's `[worker.oci] max-parallelism` — the same "limit the number of parallel build steps that can run at the same time", applied when the daemon starts rather than per build. The cap's provenance is unchanged: it was introduced by the podman-5.7.x blob-reuse SIGABRT race (see CHANGELOG/).

Variables

var AggregateCandyCapabilities = spec.AggregateCandyCapabilities

AggregateCandyCapabilities merges each candy's `capabilities:` contribution (see spec).

var BuilderPhaseTemplate = spec.BuilderPhaseTemplate

BuilderPhaseTemplate is the BuilderDef analog of FormatPhaseTemplate (see spec.BuilderPhaseTemplate).

var CandyCapabilitiesError = spec.CandyCapabilitiesError

CandyCapabilitiesError formats a missing-capabilities error (see spec).

var CheckRequiredCapabilities = spec.CheckRequiredCapabilities

CheckRequiredCapabilities returns the sorted missing `requires_capabilities:` names (see spec).

var ComputeCalVer = spec.ComputeCalVer

ComputeCalVer returns the canonical build tag for the current UTC instant.

var ComputeCalVerAt = spec.ComputeCalVerAt

ComputeCalVerAt formats t as the canonical CalVer (see spec.ComputeCalVerAt).

var ExternalizedBuilders = spec.ExternalizedBuilders

ExternalizedBuilders is THE single source of truth for which builder words are served by an EXTERNAL out-of-process plugin.

var FormatPhaseTemplate = spec.FormatPhaseTemplate

FormatPhaseTemplate looks up the (phase, venue) template string for a FormatDef (see spec.FormatPhaseTemplate). FormatDef = spec.Format, so the forwarded signature matches.

var NumCPU = runtime.NumCPU

NumCPU is a package-level override point for runtime.NumCPU so tests can inject a fixed value.

var TemplateFuncs = template.FuncMap{
	"cacheMounts": func(m []spec.CacheMount) string { return spec.RenderCacheMounts(m, -1, 0, " \\\n    ", false) },
	"cacheMountsOwned": func(m []spec.CacheMount, uid, gid int) string {
		return spec.RenderCacheMounts(m, uid, gid, " \\\n    ", true)
	},
	"cacheMountsAuto": func(m []spec.CacheMount, uid, gid int) string {
		return spec.RenderCacheMountsAuto(m, uid, gid, " \\\n    ", false)
	},

	"quote": func(s any) string {
		return fmt.Sprintf("%q", fmt.Sprint(s))
	},

	"default": func(val, fallback any) any {
		s := fmt.Sprint(val)
		if s == "" || s == "<nil>" {
			return fallback
		}
		return val
	},

	"splitFirst": func(s, sep string) string {
		parts := strings.SplitN(s, sep, 2)
		return parts[0]
	},

	"replace": strings.ReplaceAll,

	"join": func(elems any, sep string) string {
		switch v := elems.(type) {
		case []string:
			return strings.Join(v, sep)
		case []any:
			strs := make([]string, len(v))
			for i, e := range v {
				strs[i] = fmt.Sprint(e)
			}
			return strings.Join(strs, sep)
		default:
			return fmt.Sprint(elems)
		}
	},

	"printf": fmt.Sprintf,

	"shquote": kit.ShQuoteArg,

	"hasSuffix": strings.HasSuffix,

	"hasPrefix": strings.HasPrefix,

	"pkgName": PkgName,

	"anyRepoHasURL": func(repos []map[string]any) bool {
		for _, r := range repos {
			if u, ok := r["url"]; ok && fmt.Sprint(u) != "" {
				return true
			}
		}
		return false
	},
}

TemplateFuncs provides helper functions for format/builder templates. The cache-mount funcs delegate to spec.RenderCacheMounts/RenderCacheMountsAuto (relocated to spec/spec, #55 coneK3tasks) — buildkit imports spec, so the shared spec primitives are the single source (R3) for every render site.

Functions

func BootstrapPackagesForBox

func BootstrapPackagesForBox(distro *spec.ResolvedDistro) []string

BootstrapPackagesForBox returns base bootstrap packages for a resolved distro. Per-image overrides aren't currently surfaced via charly.yml; this returns just the distro defaults for now. Mirrors the VM-bootstrap engine's equivalent lookup at the OCI-image build path (the box config `from: builder:<name>` consumers). Same dispatch rules: Pacstrap.BasePackages for pacstrap-flavored, Debootstrap.BasePackages for debootstrap-flavored. Takes the resolved distro directly (not the whole ResolvedBox) so a caller holding only the distro descriptor — e.g. the wire-carried spec.BuildResolveBox.DistroDef — needs no wrapper struct.

func CandyStatus

func CandyStatus(c spec.CandyReader) string

CandyStatus returns a candy's authored maturity rung (working|testing|broken), defaulting an unset value to StatusTesting. The authoritative per-candy status source.

func CharlyBinaryUpToDate

func CharlyBinaryUpToDate(binPath, srcDir string) (bool, error)

CharlyBinaryUpToDate returns true when binPath exists and is newer than every .go file under srcDir. Returns (false, nil) for any file system state that warrants a rebuild (missing binary, missing source dir).

func CopyFileBytes

func CopyFileBytes(src, dst string) error

CopyFileBytes copies src to dst, streaming (io.Copy) rather than reading the whole file into memory — the privileged outputs can be multi-GiB (a VM disk qcow2, a rootfs tarball), and the former os.ReadFile approach allocated the full file size in RAM, an OOM risk for a 20G+ disk.

func DetectRemoteBuildRef

func DetectRemoteBuildRef(dir string, boxes []string) (string, bool)

DetectRemoteBuildRef decides whether `charly box build <boxes>` must pivot to a remote @ref source and returns that ref. An explicit remote ref among the requested boxes wins first; otherwise a thin workspace whose SOLE import is one flat remote ref auto-pivots a locally-undeclared image to that upstream source (so `cd ~/projects/ecovoyage && charly box build versa` rebuilds from upstream without any flags). Byte-equivalent to the former core BuildCmd.checkRemoteRefsAndPivot. Callers pass boxes already run through NormalizeBoxArgs.

func HostPlatform

func HostPlatform() string

HostPlatform returns the host platform in OCI format.

func NewInstallContext

func NewInstallContext(section map[string]any, cacheMounts []spec.CacheMount) *spec.InstallContext

NewInstallContext creates a spec.InstallContext from a generic PackageSection.

func NormalizeBoxArgs

func NormalizeBoxArgs(boxes []string) []string

NormalizeBoxArgs canonicalises the positional box selection shared by `charly box build` and `charly box generate`. The lone sentinel `all` (case-insensitive) collapses to nil — i.e. "every enabled box" — so `charly box build all` / `charly box generate all` behave identically to the bare no-argument form. Any other slice (including a literal "all" alongside other names) passes through unchanged: the sentinel fires ONLY when it is the sole argument, so a box that happens to be named "all" is still reachable via an explicit two-name invocation.

func PkgName

func PkgName(s string) string

PkgName strips a version specifier from a package string, leaving the bare package NAME. A candy pins an exact version in `distro: <d>. package:` so a rebuilt upstream package invalidates the install layer (the RUN text changes) — `name=version` on pac/apt/apk, `name-<version>-<rel>` on rpm. The SAME `.Packages` list feeds the UNINSTALL template, where every package manager wants the bare name (`pacman -Rs name=version` fails with "target not found"; `apk del name=version` likewise). An uninstall_template renders `{{pkgName .}}` so an install-side pin never breaks teardown. Only a suffix that begins with a DIGIT is stripped, so a genuinely hyphenated name (e.g. `foo-bar`) is left intact.

Exported so non-template consumers share the ONE canonical strip implementation (R3): deploykit's distroRepoProvidesPackage matches the bare packaging.name against a pinned `distro: <d>. package:` entry, and the `pkgName` template func points at this same function.

func RenderBootstrapScript

func RenderBootstrapScript(builder *BuilderDef, ctx any) (string, error)

RenderBootstrapScript renders the install template for a privileged bootstrap builder against a render context (the fields are documented at each call site: the OCI-image path in candy/plugin-build's runPrivilegedBootstrap, the VM-disk path in candy/plugin-vm/vm_bootstrap_engine.go's buildBootstrapRootfs).

func RenderPacstrapExtraConf

func RenderPacstrapExtraConf(p *spec.Pacstrap) string

RenderPacstrapExtraConf builds the pacman.conf fragment appended to /etc/pacman.conf inside the bootstrap container before `pacstrap` runs. It is the SINGLE source of truth for both the image bootstrap path (candy/plugin-build's runPrivilegedBootstrap) and the VM bootstrap path (candy/plugin-vm) — these previously each open-coded the rendering and drifted: the VM path dropped the per-repo SigLevel, so a SigLevel=Never repo (CachyOS) fell back to the default Required and `pacman -Sy` failed with "GPGME error: No data / corrupted PGP signature". Both paths share this function.

It emits, in order:

1. an [options] Architecture directive whenever any repo Server declares a microarch variant (e.g. x86_64_v3). pacman's default Architecture (auto → x86_64) otherwise rejects those packages with "package architecture is not valid". Architecture is cumulative in pacman, so appending this to the base config widens the accepted set rather than replacing it.
2. each [repo] block with its Server and (when set) SigLevel.

func RenderRuntimePacmanConf

func RenderRuntimePacmanConf(p *spec.Pacstrap) (string, error)

RenderRuntimePacmanConf renders the booted-guest /etc/pacman.conf for a pacstrap distro. `runtime_pacman_conf` is a Go text/template evaluated against the PacstrapDef, so the repo list is derived from the SINGLE `extra_repo` source (`{{ range .ExtraRepos }}`) rather than a second hand-maintained verbatim copy. The template adds only the runtime-specific framing ([options] header + Arch core/extra). A legacy verbatim config (no template actions) renders to itself. Returns "" when unset; surfaces malformed-template errors.

func RenderSystemPackagesFragment

func RenderSystemPackagesFragment(format string, phase spec.Phase, rawInstallContext map[string]any, distroCfg *DistroConfig) (string, error)

RenderSystemPackagesFragment renders the container-venue Containerfile fragment for a SystemPackages step. A nil FormatDef (no distro defines the format) is a LOUD error; an empty template for the phase/venue is legitimately nothing to emit (returns ""). Byte-identical to the former in-core render.

func RenderTemplate

func RenderTemplate(name, tmplStr string, ctx any) (string, error)

RenderTemplate renders a Go text/template with the given context.

func ResolveAllBox

func ResolveAllBox(cfg *spec.Config, calverTag string, dir string, opts ResolveOpts) (map[string]*ResolvedBox, error)

ResolveAllBox resolves all enabled images in the config. opts.IncludeDisabled extends the working set to images marked enabled: false (the build verb's `--include-disabled` flag flips this for one-off operational rebuilds without modifying authored config). REQUIRES opts.DistroCfg/BuilderCfg to be pre-populated (charly's ResolveAllBox wrapper fills them).

func ResolveStageParallelism

func ResolveStageParallelism(override, jobsCap int) int

ResolveStageParallelism returns the INNER concurrency for one build — the stages of a single build, distinct from the OUTER `jobs` (images per DAG level). An explicit override (>0, from `--stage-parallelism` / `CHARLY_STAGE_PARALLELISM` / `defaults.stage_parallelism`) wins. Otherwise the value is CPU-proportional, capped at `jobsCap` (`defaults.stage_parallelism_cap`, else StageParallelismCapFallback): min(NumCPU(), jobsCap). A jobsCap < 1 falls back to StageParallelismCapFallback.

The value reaches the builder through the daemon's `[worker.oci] max-parallelism`, which is where BuildKit's equivalent of `podman build --jobs` lives (see the constant above).

func ResolveStatus

func ResolveStatus(s string) string

ResolveStatus returns the effective status string. Empty defaults to StatusTesting. Accepts a single status word (working/testing/broken) — the legacy form used by older callers.

func RunPrivileged

func RunPrivileged(p PrivilegedRun) error

RunPrivileged executes the container described by p. Returns an error when the container exits non-zero or when the output file capture fails. Stdout/stderr stream live to the caller. Always passes --privileged + --rm + -v /dev:/dev. Callers do NOT need to repeat those mounts in p.Mounts.

func StatusSeverity

func StatusSeverity(s string) int

StatusSeverity returns a numeric severity for status comparison.

func ToMapSlice

func ToMapSlice(v any) []map[string]any

ToMapSlice converts an interface{} to []map[string]any. Accepts both `[]interface{}` (legacy raw-YAML decode shape) and `[]map[string]any` (typed shape produced by the post-2026-05 derivePackageSectionsFromCalamares bridge that copies `DistroPackages.Repos` directly into PackageSection.Raw).

func ToStringSlice

func ToStringSlice(v any) []string

ToStringSlice converts an interface{} to []string.

func WorstStatus

func WorstStatus(a, b string) string

WorstStatus returns the more severe of two status values.

Types

type AggregatedCandyCaps

type AggregatedCandyCaps = spec.AggregatedCandyCaps

Aliases onto the CUE-sourced spec types ResolvedBox references (DistroDef / DistroConfig / BuilderConfig are already bound in format_config.go, same package). These read unchanged in the moved code.

type BuilderConfig

type BuilderConfig = spec.BuilderConfig

Local aliases onto the CUE-sourced spec build-vocabulary config types, so buildkit's build-engine code (config_resolve.go / resolved_box.go / system_packages.go) reads unchanged without importing charly core. #55 step 3-III relocated the DistroConfig/BuilderConfig CONTAINERS + their vocabulary-resolution methods (ResolveDistro / ResolveInherits / AllFormatNames / FindFormat / ValidFormat / ExpandPackageInheritance / ValidBuilderType / BuilderNames) and the WrapDistroDef / DistroTagChain free functions to spec (schema/{distro,builder}.cue + spec/{distro,builder}_config_methods.go), so every charly/plugin file that uses ONLY these value types drops its sdk/buildkit import for spec — the import-purity lever. buildkit keeps these thin aliases exactly as it does for DistroDef/BuilderDef/BuilderMap.

type BuilderDef

type BuilderDef = spec.Builder

Local aliases onto the CUE-sourced spec build-vocabulary config types, so buildkit's build-engine code (config_resolve.go / resolved_box.go / system_packages.go) reads unchanged without importing charly core. #55 step 3-III relocated the DistroConfig/BuilderConfig CONTAINERS + their vocabulary-resolution methods (ResolveDistro / ResolveInherits / AllFormatNames / FindFormat / ValidFormat / ExpandPackageInheritance / ValidBuilderType / BuilderNames) and the WrapDistroDef / DistroTagChain free functions to spec (schema/{distro,builder}.cue + spec/{distro,builder}_config_methods.go), so every charly/plugin file that uses ONLY these value types drops its sdk/buildkit import for spec — the import-purity lever. buildkit keeps these thin aliases exactly as it does for DistroDef/BuilderDef/BuilderMap.

type BuilderMap

type BuilderMap = spec.BuilderMap

Aliases onto the CUE-sourced spec types ResolvedBox references (DistroDef / DistroConfig / BuilderConfig are already bound in format_config.go, same package). These read unchanged in the moved code.

type CacheMount

type CacheMount struct {
	Dst     string // Container-side mount path; canonical id source.
	Sharing string // "locked"/"shared"/"private" for shared caches; ignored for owned.
	UID     int    // For owned caches; sentinel -1 means "shared" form.
	GID     int
}

CacheMount is the RENDER-time cache-mount value (a resolved Containerfile `--mount=type=cache,…` directive). Distinct from the authoring spec.CacheMount (dst/sharing/owned): this one carries the concrete uid/gid the owned form resolved to (sentinel UID == -1 = the shared form). Produced by SharedCacheMount/OwnedCacheMount from the authoring def.

func OwnedCacheMount

func OwnedCacheMount(dst string, uid, gid int) CacheMount

OwnedCacheMount returns a cache-mount value for non-root user caches (pixi/npm/cargo). UID becomes part of the id namespace.

func SharedCacheMount

func SharedCacheMount(dst, sharing string) CacheMount

SharedCacheMount returns a cache-mount value for root-installed system caches (dnf/apt/pacman/downloads). Sharing defaults to "locked".

func (CacheMount) String

func (m CacheMount) String() string

String renders the CacheMount as a Containerfile `--mount=type=cache,...` flag, delegating to spec.FormatCacheMount — the single-source formatter (#55 coneK3tasks relocated the slice renderers + the per-mount formatter to spec/spec so charly core can render cache mounts without an sdk/buildkit import). The `id=` field is derived from Dst (and UID for owned caches), keeping the cache stable across layer-hash changes during iterative builds.

type DistroConfig

type DistroConfig = spec.DistroConfig

Local aliases onto the CUE-sourced spec build-vocabulary config types, so buildkit's build-engine code (config_resolve.go / resolved_box.go / system_packages.go) reads unchanged without importing charly core. #55 step 3-III relocated the DistroConfig/BuilderConfig CONTAINERS + their vocabulary-resolution methods (ResolveDistro / ResolveInherits / AllFormatNames / FindFormat / ValidFormat / ExpandPackageInheritance / ValidBuilderType / BuilderNames) and the WrapDistroDef / DistroTagChain free functions to spec (schema/{distro,builder}.cue + spec/{distro,builder}_config_methods.go), so every charly/plugin file that uses ONLY these value types drops its sdk/buildkit import for spec — the import-purity lever. buildkit keeps these thin aliases exactly as it does for DistroDef/BuilderDef/BuilderMap.

type DistroDef

type DistroDef = spec.ResolvedDistro

Local aliases onto the CUE-sourced spec build-vocabulary config types, so buildkit's build-engine code (config_resolve.go / resolved_box.go / system_packages.go) reads unchanged without importing charly core. #55 step 3-III relocated the DistroConfig/BuilderConfig CONTAINERS + their vocabulary-resolution methods (ResolveDistro / ResolveInherits / AllFormatNames / FindFormat / ValidFormat / ExpandPackageInheritance / ValidBuilderType / BuilderNames) and the WrapDistroDef / DistroTagChain free functions to spec (schema/{distro,builder}.cue + spec/{distro,builder}_config_methods.go), so every charly/plugin file that uses ONLY these value types drops its sdk/buildkit import for spec — the import-purity lever. buildkit keeps these thin aliases exactly as it does for DistroDef/BuilderDef/BuilderMap.

type FormatDef

type FormatDef = spec.Format

Local aliases onto the CUE-sourced spec build-vocabulary config types, so buildkit's build-engine code (config_resolve.go / resolved_box.go / system_packages.go) reads unchanged without importing charly core. #55 step 3-III relocated the DistroConfig/BuilderConfig CONTAINERS + their vocabulary-resolution methods (ResolveDistro / ResolveInherits / AllFormatNames / FindFormat / ValidFormat / ExpandPackageInheritance / ValidBuilderType / BuilderNames) and the WrapDistroDef / DistroTagChain free functions to spec (schema/{distro,builder}.cue + spec/{distro,builder}_config_methods.go), so every charly/plugin file that uses ONLY these value types drops its sdk/buildkit import for spec — the import-purity lever. buildkit keeps these thin aliases exactly as it does for DistroDef/BuilderDef/BuilderMap.

type InitConfig

type InitConfig = spec.InitConfig

InitConfig represents the `init:` section of the embedded vocabulary (charly/charly.yml).

type MergeConfig

type MergeConfig = spec.MergeConfig

Aliases onto the CUE-sourced spec types ResolvedBox references (DistroDef / DistroConfig / BuilderConfig are already bound in format_config.go, same package). These read unchanged in the moved code.

type PrivilegedRun

type PrivilegedRun struct {
	// Image is the builder image ref (e.g. arch-pacstrap-builder:CALVER).
	Image string
	// Script is the bash body executed inside the container. Run via
	// `bash -s <<'EOF' ... EOF` so quoting in the script body is preserved.
	Script string
	// Env lists KEY=VALUE pairs forwarded to the container.
	Env []string
	// Mounts lists "src:dst[:opts]" host-path bind mounts. /dev is always
	// added so loop devices created by losetup are visible.
	Mounts []string
	// OutputPath is an absolute path inside the container whose contents
	// must be copied out after the container exits successfully. May be
	// empty when the script writes directly to a host-bind-mounted path.
	OutputPath string
	// OutputDest is the absolute host path where OutputPath is written.
	// Required when OutputPath is set; ignored otherwise.
	OutputDest string
	// MinFreeBytes is the minimum free space required on BOTH the staging
	// directory (where the container writes the output) and the OutputDest
	// directory (where the output is copied). When > 0, RunPrivileged
	// statfs's both locations before the container runs and fails with a
	// clear error naming the directory, the free space, and the required
	// space — instead of the container dying cryptically mid-write with
	// "No space left on device". Callers that know their output size (a VM
	// disk, a rootfs tarball) MUST set it; the image-build bootstrap sets a
	// default floor.
	MinFreeBytes int64
}

PrivilegedRun describes a single privileged-container invocation: a script body executed inside a builder image with --privileged -v /dev:/dev. Used for pacstrap/debootstrap rootfs bootstrap and for VM disk-build chroots.

type ResolveOpts

type ResolveOpts struct {
	IncludeDisabled      bool            // skip the `enabled: false` check
	IncludeDisabledNames map[string]bool // when non-empty, scope IncludeDisabled to these names only
	// RequestedBoxes are the explicit build targets (`charly box build <name>`). A qualified name
	// here (e.g. `charly.arch-builder`) is pulled into the resolved set even when it isn't
	// reachable as a base/builder of a root image.
	RequestedBoxes []string
	DistroCfg      *DistroConfig
	BuilderCfg     *BuilderConfig
}

ResolveOpts carries the box-resolution-relevant subset of charly's own (wider) ResolveOpts — projected in by charly's thin wrapper. IncludeDisabled/IncludeDisabledNames/RequestedBoxes are pure value/set fields; DistroCfg/BuilderCfg are the project's build vocabulary the caller must supply (charly's wrapper fills them via LoadBuildConfigForBox when absent). Charly-only fields that no function in this file reads (ExtraCandyRefs, InitCfg — consumed solely by charly/layers.go's ScanAllCandyWithConfigOpts) deliberately stay OUT of this type; charly's own ResolveOpts carries them alongside this projected subset.

func (ResolveOpts) ShouldIncludeDisabled

func (opts ResolveOpts) ShouldIncludeDisabled(name string) bool

ShouldIncludeDisabled reports whether name's disabled gate should be bypassed under opts.

type ResolvedBox

type ResolvedBox = spec.BuildResolvedBox

ResolvedBox represents a fully resolved box configuration. #55 step3 unit 3a: the wire-clean value fields (Name/Version/Distro/Tags/User/…) moved to spec.ResolvedBox (spec/spec/resolved_box.go) — the shared contract type charly core's render-seam floor + the "resolved-project" envelope projector + candy/plugin-build all read/construct. SPIKE (value-type relocation, #55 keystone): the embedding wrapper itself moved to spec.BuildResolvedBox (spec/spec/build_resolved_box.go) — every one of its fields already resolved to a spec.* type (DistroConfig/BuilderConfig/ResolvedDistro/ ResolvedInit/AggregatedCandyCaps/BakedLabelSet are all CUE-generated), so the wrapper carried zero buildkit-only content. This is now a zero-churn alias — every existing buildkit/deploykit/candy call site (composite literals, field selectors) compiles unchanged.

func ResolveBox

func ResolveBox(cfg *spec.Config, name string, calverTag string, dir string, opts ResolveOpts) (*ResolvedBox, error)

ResolveBox resolves a single box's configuration by applying defaults.

type ResolvedInit

type ResolvedInit = spec.ResolvedInit

Aliases onto the CUE-sourced spec types ResolvedBox references (DistroDef / DistroConfig / BuilderConfig are already bound in format_config.go, same package). These read unchanged in the moved code.