Home /Modules/operating-system/CREATOR.DOCTRINE.md

CREATOR.DOCTRINE.md

lib/operating-system/os-creator/CREATOR.DOCTRINE.md · 127 line(s) · markdown

OS Creator Doctrine — the ordered composition of a Creator document

Schema: os-creator.xsd · Version: 1.0.0

This doctrine is the normative statement of how the OS Creator parts go together — in order, not in an unordered way — and how the SLeeLa compiler and tooling keep that integrity. The machine-checkable form is the XSD; this document is its rationale and the contract authors follow.

1. The parts go one way: firmware → desktop

An OS model (SLOSModel) composes its layers in the exact order a system boots. A Creator document MUST present them in this sequence (the <xs:sequence> of os-creator.xsd):

identity → shape → arch(+) → bootloader → kernel → base-drivers
        → filesystem → [swap] → packages → services → [compat] → [desktop]

Rationale — each layer depends only on the ones before it:

  1. identity / shape / arch — what OS, which family, which CPU(s). The shape fixes every downstream default.
  2. bootloader — firmware + loader; nothing boots without it.
  3. kernel — the kernel the loader hands control to (family + version).
  4. base-drivers — the minimum-boot driver series. The bus and storage drivers MUST be present here or the kernel cannot reach the root filesystem; this is why base-drivers precede filesystem.
  5. filesystem — the root filesystem the early userspace mounts, reachable only because the storage driver above exists.
  6. swap (optional) — paging store; meaningful only once a filesystem is chosen.
  7. packages — the userland seed installed into the mounted rootfs.
  8. services — what the init manager starts, from the installed packages.
  9. compat (optional) — foreign-OS execution; a userspace capability that needs the services/libraries above.
  10. desktop (optional) — the session stack, last and topmost.

Required vs. optional is normative: swap, compat, and desktop are minOccurs="0"; everything else is mandatory. A server edition omits desktop.

2. What may not go together

The XSD encodes the illegal combinations as closed value sets and cardinalities:

3. How the compiler keeps integrity — by version

A SLeeLa source that drives the OS Creator binds itself to this schema with a pragma on an early line (after #sleela):

#sleela 1.11
#schema os-creator/os-creator.xsd 1.0.0

The compiler (resolveSchemaReference in impl/frontend/version.{h,cpp}, invoked from checkSyntaxVersion) performs code recognition of this binding on every check / run / compile:

Full structural XSD validation of an exported Creator document (the XML a developer can serialise from an SLOSModel) is performed by external tooling / CI against the same os-creator.xsd. The division is deliberate: the compiler guarantees reference integrity + version compatibility at build time (fast, always-on); the XSD is the single normative structure both the compiler's doctrine and the external validator agree on.

4. Versioning the doctrine

The schema carries version="1.0.0" on its root and in its #schema pragma. Changes follow semantic versioning of the composition contract:

Bump maxSupportedSchema() in version.h when the compiler is taught a new Creator schema version, and record the change here and in the XSD's version.

5. The objects, in order (quick reference)

#LayerSLeeLa objectRequiredNotes
1identitySLOSModelyesname/version/edition
2shapeSLOSShapeyesLinux/Windows/macOS
3archSLArchitectureSetyes≥1 target
4bootloaderSLBootloaderSpecyesfirmware + loader
5kernelSLKernelSpec (+SLKernelCatalog)yesfamily + version
6base-driversSLBaseDriverSeries (+SLDriverSource)yesboot bus+storage
7filesystemSLFilesystemLayout (+SLFilesystemCatalog)yesrootable fs
8swapSLSwapConfignokind + quality
9packagesSLPackageSetyes≥1 package
10servicesSLServiceSetyesinit manager
11compatSLCompatSetnoforeign-OS routes
12desktopSLDesktopSpecnoomitted on Server

The emitters (SLBaseDriverEmitter, SLCompatLoaderEmitter, SLCEmitter, SLCppEmitter, …) consume these in this order to write /os and the generated tree; the order here is the order there.