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 defaults to the release the kernel was verified against (schema.DefaultSchemaVersion); WithCoreVersion overrides it. 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 ¶
func Roots(entries []Entry, opts ...RootOption) []Dep
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 unless WithCoreVersion overrides it. 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.
type RootOption ¶
type RootOption func(*rootConfig)
RootOption configures Roots.
func WithCoreVersion ¶
func WithCoreVersion(version string) RootOption
WithCoreVersion pins core at version (bare or "v"-prefixed SemVer) instead of the kernel's verified release. Fixtures and forward testing use it; a frontend normally leaves the default.
Source Files