Documentation
¶
Overview ¶
Package platformmodule generates a platform CUE module from catalog coordinates (enhancement 0019 D5/D13). A platform is a CUE module that imports its catalogs, and the kernel's only platform input is such a module on disk ([kernel.Kernel.AcquirePlatformFromDir]); a frontend that starts from typed coordinates (a Platform CR, a seeded local default) turns them into that module here instead of writing its own generator.
Three seams, each independently testable:
- Generate is pure: typed input plus the resolved dependency closure in, deterministic file bytes out. The same input always yields byte-identical files (cue.mod/module.cue in modfile canonical format, platform.cue embedding core.#Platform and importing every catalog under a positional alias).
- Closure derives the module's full dependency list from the pinned modules' published module files: the roots (Roots: core and every subscribed catalog) plus everything they transitively require, at the maximum version any requirement names. It is the tidied list a `cue mod tidy` would write, computed once at generation (0019 D13). Module files are read through a caller-configured ModFileSource (NewRegistry); tests supply a fixture graph.
- Files.WriteTo places the generated files under a caller-owned directory. Directory lifecycle (generations, staging swaps, retention) stays with the frontend.
The core pin is the release the kernel was verified against (schema.DefaultSchemaVersion); a caller that needs another core build assembles its Dep roots directly. The generated module's own path is caller input (Input.ModulePath) and lives under the reserved, never-published platforms namespace (0019 D6).
This package is opt-in helper convenience (see package opm/helper): a frontend MAY write its platform module by hand instead.
Index ¶
Constants ¶
const ( // CorePath is the major-qualified module path of the core schema the // generated module embeds. CorePath = "opmodel.dev/core@v2" // LanguageVersion is the generated module's declared CUE language // version: the floor every published first-party module declares and the // render build requires for cue.mod/local-module.cue. LanguageVersion = "v0.17.0" // ModuleFileName and PlatformFileName are the two files a generated // module consists of, relative to the module directory. ModuleFileName = "cue.mod/module.cue" PlatformFileName = "platform.cue" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Dep ¶
Dep is one pinned dependency of the generated cue.mod: a major-qualified module path and a canonical "v"-prefixed version.
func Closure ¶
Closure derives the generated module's full dependency list from roots: a breadth-first walk over each reachable module version's published module file, selecting the maximum version per major-qualified path, the roots participating in the maximum. This is minimum version selection computed the way `cue mod tidy` computes it (0019 D13: tidying happens once, at platform-module generation), minus the prune of modules no import reaches, which pins a path nothing evaluates and is harmless. Derived entries carry no default-major marker; `cue mod tidy` writes none for a platform either, because the platform imports nothing unqualified. Local replacements (cue.mod/local-module.cue, the "local" path) are skipped.
A root or transitive requirement naming an unpublished build fails with an error naming the module path and version, the same wording the CUE resolver uses for a missing pin. The walk honours ctx cancellation.
func Roots ¶
Roots returns the dependency roots the closure is derived from: the core pin plus every entry's catalog, disabled entries included (a disabled entry still imports its catalog). Core is pinned at schema.DefaultSchemaVersion, the release the kernel was verified against; a caller that needs a different core build assembles its []Dep roots directly. Versions are canonicalised with the "v" prefix cue.mod requires; subscriptions carry bare SemVer.
type Entry ¶
Entry is one catalog subscription in the shape Generate consumes: the major-qualified catalog path (the registry key), the bare SemVer build the subscription names and whether the subscription is enabled.
type Files ¶
Files maps a path relative to the module directory to the file's bytes.
func Generate ¶
Generate renders the module's two files from in. It is pure and deterministic: entries and dependencies are emitted in sorted path order whatever order they arrive in, so the same input always produces byte-identical content. Each registry entry stamps the subscription's version as the entry's expected `version`, which unifies with the schema's readout of the imported catalog so wrong bytes are a build conflict naming the entry (0019 D13 tripwire).
func (Files) WriteTo ¶
WriteTo places the generated files under dir, creating parent directories as needed. A file name that would resolve outside dir is refused before anything is written. The helper owns no directory lifecycle: whether dir is a fresh generation directory, a staging directory later swapped into place, or a cache entry is the frontend's policy.
type Input ¶
Input is everything Generate needs. Name and Type are the platform's metadata.name and type; ModulePath is the generated module's own identity (a reserved, never-published platforms path such as "opmodel.dev/platforms/cluster@v0", 0019 D6); Entries are the catalog subscriptions; Deps is the resolved dependency closure (see Closure), which MUST contain a pin for core and for every entry's catalog.
type ModFileSource ¶
type ModFileSource interface {
ModFile(ctx context.Context, mv module.Version) (*modfile.File, error)
}
ModFileSource yields a published module's cue.mod/module.cue. It is the one method of modconfig.Registry the closure needs, kept as a narrow interface so tests can supply a fixture graph without a registry.
func NewRegistry ¶
func NewRegistry(cfg RegistryConfig) (ModFileSource, error)
NewRegistry returns a module-file source resolving through cfg. Module files it fetches are the same artifacts a build fetches, so a closure derivation never adds an artifact class to the frontend's registry path.
type RegistryConfig ¶
type RegistryConfig struct {
// Registry is the CUE registry mapping (CUE_REGISTRY syntax) module files
// resolve through. Empty falls back to CUE_REGISTRY in Env.
Registry string
// ClientType is reported to registries in the User-Agent header. Empty
// falls back to modconfig's own default ("cuelang.org/go").
ClientType string
// Env is the environment the CUE module cache location (CUE_CACHE_DIR)
// and, when Registry is empty, CUE_REGISTRY are read from. Nil selects
// modconfig's default, the current process environment; passing nil is
// the caller's explicit choice, never a hidden lookup by the helper.
Env []string
}
RegistryConfig is the caller-supplied configuration a registry-backed ModFileSource resolves through. Nothing here is read from the process by the helper itself (kernel neutrality): the frontend states every value.
Source Files