Documentation
¶
Overview ¶
Package module defines the Module type, mirroring the #Module definition in the OPM core schema. A Module represents the parsed module definition before it is built into an instance.
Debug overlays. The CUE schema includes a `debugValues` field on every `#Module` for author-supplied example values used by build/validation tooling. `debugValues` is a Module field — NOT a separate kernel artifact — and it is read off Module.Package via schema.DebugValues. Whether a frontend layers debugValues into the values stack is a policy decision that lives in the helper layer; the kernel itself never observes the distinction.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CueContextOwner ¶
CueContextOwner is the minimal context-owner interface accepted by the constructor helpers. *kernel.Kernel satisfies it; tests may pass any value exposing a *cue.Context. The interface lives in opm/module to keep the constructor's import surface free of opm/kernel.
type Instance ¶
type Instance struct {
// Metadata is the decoded instance-level metadata cache. May be nil when
// the metadata could not be decoded.
Metadata *InstanceMetadata
// Package is the loaded, concrete CUE value for the instance artifact.
// Source of truth for every field reachable via opm/schema, including
// the embedded #module reference at schema.Module.
Package cue.Value
// Source is the staged source tree the instance package was built from,
// so a follow-on build can import the instance as a package. It is
// stamped at exactly two sites: Kernel.SynthesizeInstance (overlay mode,
// the synthesized package inside the module's staged root) and
// Kernel.AcquireInstanceFromDir (on-disk mode, the loaded directory). It
// is nil for instances constructed from a bare value
// (NewInstanceFromValue, Kernel.ProcessModuleInstance called directly).
Source *Source
}
Instance is an OPM #ModuleInstance artifact in the unified artifact shape.
Package is the source of truth: it is the concrete, values-filled CUE value for the instance and every kernel-internal read (components subtree, source module, transformer match data) goes through Package.LookupPath with paths from opm/schema.
Metadata is an ergonomic decoded projection of the instance-level metadata stamped at construction. It is a cache, not a parallel source of truth — when Metadata and the corresponding subtree of Package disagree, Package wins.
Was: Release
func NewInstanceFromValue ¶
func NewInstanceFromValue(_ CueContextOwner, v cue.Value) (*Instance, error)
NewInstanceFromValue builds a *Instance from a raw CUE artifact value. The supplied k is currently unused but preserved in the signature so future kernel-scoped state can be threaded without an API break.
The function decodes InstanceMetadata via schema.DecodeInstanceMetadata and stores the input cue.Value unmodified in Package. Errors return a nil *Instance.
Was: NewReleaseFromValue
func (*Instance) Components ¶
Components returns the instance's components value as evaluated, definition fields (#resources, #traits, #blueprints, #names) included. It is a read for frontends and tests: the render build reads the same field in CUE, inside the generated glue, and never through this accessor.
func (*Instance) ConfigSchema ¶
ConfigSchema returns the embedded source module's #config schema reachable via schema.Module followed by schema.Config on r.Package.
All failure modes return the zero cue.Value (not an error): a nil receiver, a missing #module reference, or a missing #config definition on the embedded module.
type InstanceMetadata ¶
type InstanceMetadata = schema.InstanceMetadata
InstanceMetadata is a re-export of schema.InstanceMetadata so callers can keep working with `module.InstanceMetadata`.
Was: ReleaseMetadata
type Module ¶
type Module struct {
// Metadata is the decoded module-level metadata cache. Authoritative data
// lives in Package; Metadata exists for hot-path access (logging, name
// lookups). May be nil when the metadata could not be decoded.
Metadata *ModuleMetadata `json:"metadata"`
// Package is the loaded CUE value for the module artifact. Source of
// truth for every field reachable via opm/schema's path vars.
Package cue.Value `json:"-"`
// Source is the module's staged source tree, populated only when the
// module was acquired through the source-carrying registry path
// (Kernel.AcquireModuleFromRegistry): always overlay mode, never on-disk.
// It is nil otherwise. Consumers that must build inside the module's own
// root (e.g. synth.Instance) gate on HasSource(). See [Source] for the
// full two-mode contract shared with Instance and Platform.
Source *Source `json:"-"`
}
Module represents an OPM #Module artifact in the unified artifact shape.
Package is the source of truth: it is the loaded CUE value for the module and every kernel-internal read (the #config schema, components subtree) goes through Package.LookupPath with paths from opm/schema.
Metadata is an ergonomic decoded projection of the module-level metadata stamped at construction. It is a cache, not a parallel source of truth — when Metadata and the corresponding subtree of Package disagree, Package wins.
func NewModuleFromValue ¶
func NewModuleFromValue(_ CueContextOwner, v cue.Value) (*Module, error)
NewModuleFromValue builds a *Module from a raw CUE artifact value. The supplied k is currently unused but preserved in the signature so future kernel-scoped state (logger, tracer, clock) can be threaded without an API break.
The function decodes ModuleMetadata via schema.DecodeModuleMetadata and stores the input cue.Value unmodified in Package. Errors return a nil *Module — partial values are never returned.
func (*Module) ConfigSchema ¶
ConfigSchema returns the module's #config schema reachable via schema.Config on m.Package.
All failure modes return the zero cue.Value (not an error): a nil receiver or a missing #config definition on the module package. Callers detect failure via the returned value's Exists() method.
func (*Module) HasSource ¶
HasSource reports whether the module carries a staged registry source tree (non-nil Source with a populated overlay). Consumers that must build inside the module's own root — e.g. synth.Instance — gate on this and return a deterministic error when it is false, rather than silently fetching.
type ModuleMetadata ¶
type ModuleMetadata = schema.ModuleMetadata
ModuleMetadata is the decoded module-level identity record. It is a re-export of schema.ModuleMetadata so callers can keep working with `module.ModuleMetadata` without taking a transitive dependency on opm/schema at every reference site.
type Source ¶
type Source struct {
// Root is the absolute module root of the tree: the load.Config.ModuleRoot
// a consumer builds against. In overlay mode it is the synthetic root every
// Overlay key sits under; in on-disk mode it is a real directory.
Root string
// Pkg is the package directory relative to Root that holds the artifact's
// CUE package. Empty means the root package (".").
Pkg string
// Overlay maps absolute paths under Root to their file contents, exactly as
// load.Config.Overlay expects, including cue.mod/module.cue. Nil selects
// on-disk mode: the tree is read from Root on the filesystem.
Overlay map[string]load.Source
}
Source is the staged source tree an artifact was loaded or synthesized from: the module root the tree is keyed under, the package directory inside it, and (for in-memory trees) the load.Config.Overlay carrying the files.
A Source is in one of two modes:
- Overlay mode (Overlay non-empty): the tree lives in memory, keyed under the deterministic synthetic Root. This is how a module fetched from a registry is staged (Kernel.AcquireModuleFromRegistry) and how a synthesized instance is staged inside its module's tree (opm/helper/synth, surfaced by Kernel.SynthesizeInstance).
- On-disk mode (Overlay nil): the tree lives at Root on the real filesystem. This is how an artifact acquired from a directory is described (Kernel.AcquirePlatformFromDir, Kernel.AcquireInstanceFromDir).
It exists so an artifact can be RE-USED as the input of a follow-on build: a module acquired from the registry becomes the main module of the synth build (so its already-tidied cue.mod/module.cue drives transitive dependency resolution), and an instance or platform carrying its tree can be imported as a package by a later render build. Carrying the staged source on the artifact avoids a second fetch or a second directory load.
Source is carried by Module (registry path only), Instance (synthesis and directory acquire) and Platform (directory acquire; platform.Source is an alias of this type). It is nil for artifacts constructed from a bare value (e.g. a unit-test CompileString).
Source Files