buildspec

Documentation

Overview

Package buildspec is the KIDS build-spec schema + validating loader (VSL T0a.1, CQ9): the declarative, diffable git source of a KIDS BUILD (#9.6), kids/<pkg>.build.json. It is the human-readable form of a package definition — component list, Required Builds, the environment-check routine, and the ICR list — that `v pkg build` consumes to produce a transport global / .KID. See msl-vsl-coordination-implementation-plan.md §7.2.

Index

• Constants
• Variables
• type Components
• type FileComp
• type ICR
• type ParamDef
• type ParamEntity
• type RequiredBuild
• type Spec
  • func Load(path string) (*Spec, error)
  • func Parse(data []byte) (*Spec, error)
  • func (s *Spec) InstallName() string
  • func (s *Spec) Validate() error

Constants

const (
	ActionWarn         = "WARNING ONLY"                 // warn, continue
	ActionLeaveGlobal  = "DON'T INSTALL, LEAVE GLOBAL"  // block unless prerequisite present; keep its global
	ActionRemoveGlobal = "DON'T INSTALL, REMOVE GLOBAL" // block unless prerequisite present; remove its global
)

Required-build install actions (KIDS BUILD #9.6 REQUIRED BUILD #11 multiple; architecture §3.1).

const (
	LocalFileMin = 999000
	LocalFileMax = 999999
)

Local/test FileMan file-number range (VA-reserved 999000-999999). A v-pkg DD-install ships only throwaway files in this band — never a national file.

const (
	RoutineNameMaxStd  = 8
	RoutineNameMaxLong = 31
)

Routine-name length caps. RoutineNameMaxStd is the legacy SAC/DSM-era convention (a 2-4 char namespace + remainder, 8 total). RoutineNameMaxLong is the modern M engine limit honored by YottaDB and IRIS (31 significant characters) — used when a spec sets allowLongNames. KIDS itself (transport global, string-subscript keyed) and XINDEX impose no name-length limit; the 8 is a convention, the 31 is the real engine bound.

Variables

var ParamDataTypeCode = map[string]string{
	"free text":       "F",
	"numeric":         "N",
	"yes/no":          "Y",
	"set of codes":    "S",
	"date/time":       "D",
	"pointer":         "P",
	"word processing": "W",
}

ParamDataTypeCode maps a human value-data-type name to the #8989.51 field 1.1 (VALUE DATA TYPE) set-of-codes value. Free text is the default; the rest are accepted for completeness.

var ParamEntityIEN = map[string]string{
	"DEV": "3.5",
	"DIV": "4",
	"SYS": "4.2",
	"PKG": "9.4",
	"LOC": "44",
	"SRV": "49",
	"USR": "200",
	"CLS": "8930",
}

ParamEntityIEN maps a parameter-entity abbreviation to its #8989.518 (PARAMETER ENTITY) IEN. #8989.518 is DINUM'd to the pointed-to file number, so these IENs are national constants — portable across YDB and IRIS VistA.

var RequiredBuildActionCode = map[string]int{
	ActionWarn:         0,
	ActionRemoveGlobal: 1,
	ActionLeaveGlobal:  2,
}

RequiredBuildActionCode maps a Required-Build action to its #9.611 ACTION set-of-codes value (0 = warn, 1 = don't install/remove global, 2 = don't install/leave global).

Types

type Components

type Components struct {
	Routines             []string   `json:"routines,omitempty"`
	Files                []FileComp `json:"files,omitempty"`
	Options              []string   `json:"options,omitempty"`
	Keys                 []string   `json:"keys,omitempty"`                 // security keys
	Parameters           []string   `json:"parameters,omitempty"`           // XPAR parameter names (reference only)
	ParameterDefinitions []ParamDef `json:"parameterDefinitions,omitempty"` // XPAR #8989.51 PARAMETER DEFINITION components (shipped as data)
	Protocols            []string   `json:"protocols,omitempty"`
	Templates            []string   `json:"templates,omitempty"`
	RPCs                 []string   `json:"rpcs,omitempty"`
	MailGroups           []string   `json:"mailGroups,omitempty"`
	HL7                  []string   `json:"hl7,omitempty"`
}

Components is the BUILD component list (#9.6). Each slice is omitempty so a spec lists only what it ships.

type FileComp

type FileComp struct {
	Number     float64 `json:"number"`
	Name       string  `json:"name,omitempty"`
	GlobalRoot string  `json:"globalRoot,omitempty"` // data global, e.g. "^DIZ(999000,"; default derived from Number
}

FileComp is a FileMan FILE component shipped as a KIDS data-dictionary export. For VSL M3.T1 the supported shape is a brand-new throwaway file with a single free-text .01 NAME field (the minimal transform-invariant DD); Number is a local/test file number (999000-999999) and GlobalRoot is its data global (defaulting to ^DIZ(<file>,).

type ICR

type ICR struct {
	Number    int    `json:"number"`
	Name      string `json:"name,omitempty"`
	Custodian string `json:"custodian,omitempty"`
}

ICR is a DBIA/Integration Control Registration the package depends on.

type ParamDef

type ParamDef struct {
	Name        string        `json:"name"`                  // #8989.51 .01 NAME (uppercase, e.g. "VSL GREETING")
	DisplayText string        `json:"displayText,omitempty"` // #8989.51 .02 DISPLAY TEXT
	DataType    string        `json:"dataType,omitempty"`    // value data type; default "free text"
	Entities    []ParamEntity `json:"entities,omitempty"`    // ALLOWABLE ENTITIES (#8989.513) — where the param may be set
}

ParamDef is an XPAR PARAMETER DEFINITION (#8989.51) shipped as a KIDS KRN component — the build creates the definition (not a value) at install time. DataType/Entity are human names resolved to their #8989.51 codes / #8989.518 IENs by ParamDataTypeCode / ParamEntityIEN.

type ParamEntity

type ParamEntity struct {
	Entity     string `json:"entity"`               // entity abbreviation: SYS, USR, PKG, …
	Precedence int    `json:"precedence,omitempty"` // #8989.513 .01 PRECEDENCE; default 1
}

ParamEntity is one ALLOWABLE ENTITIES row of a ParamDef: which entity the parameter may be set at, and its precedence.

type RequiredBuild

type RequiredBuild struct {
	Name   string `json:"name"`   // NAMESPACE*VERSION[*PATCH]
	Action string `json:"action"` // one of the Action* constants
}

RequiredBuild is a KIDS Required Build (#11) — a prerequisite build + the action KIDS takes when it is absent.

type Spec

type Spec struct {
	Package        string          `json:"package"`         // NAMESPACE (e.g. ZZSKEL)
	Version        string          `json:"version"`         // e.g. 1.0
	Patch          string          `json:"patch,omitempty"` // e.g. 1 (optional)
	Components     Components      `json:"components"`
	RequiredBuilds []RequiredBuild `json:"requiredBuilds,omitempty"`
	EnvCheck       string          `json:"envCheck,omitempty"` // environment-check routine name (XPDENV)
	ICRs           []ICR           `json:"icrs,omitempty"`     // DBIA/ICR agreements the package relies on

	// AllowLongNames opts the build out of the legacy 8-char SAC routine-name
	// convention, raising the cap to the M engine limit (RoutineNameMaxLong).
	// The M-naming character rules still bind. This is a deliberate, committed
	// policy choice — see the org "modern routine-name length policy" ADR — and
	// is appropriate only for modern YDB/IRIS targets (it forgoes legacy
	// GT.M/Caché %RO portability and formal SAC/national release without a
	// later rename).
	AllowLongNames bool `json:"allowLongNames,omitempty"`
}

Spec is one KIDS build definition (kids/<pkg>.build.json).

func Load

func Load(path string) (*Spec, error)

Load reads and validates a build spec from a kids/<pkg>.build.json file.

func Parse

func Parse(data []byte) (*Spec, error)

Parse decodes a build spec from JSON (rejecting unknown fields — a typo'd key is an error, not a silent drop) and validates it.

func (*Spec) InstallName

func (s *Spec) InstallName() string

InstallName is the KIDS install name NAMESPACE*VERSION[*PATCH].

func (*Spec) Validate

func (s *Spec) Validate() error

Validate checks the spec is a usable KIDS build definition.