How cia-foundation/templeos works
Purpose and Execution Model
TempleOS is a self-hosted, 64-bit operating system written in HolyC and assembly. It boots from an ISO/CD/DVD or VM-mounted image; source is compressed and compiled only inside the running OS by its native compiler. There is no conventional host-side build pipeline. The root startup path is StartOS.HC, with bootstrap code in 0000Boot/0000Kernel.BIN.C and kernel initialization centered on Kernel/KMain.HC.
Boot, Kernel, and Hardware Boundary
The boot sequence transitions through 16-, 32-, and 64-bit startup stages, then initializes kernel globals, memory, tasks, interrupts, display, and devices. Core paths: Kernel/KStart16.HC, Kernel/KStart64.HC, Kernel/KLoad.HC. Hardware-facing services include ATA/CD/DVD block devices, keyboard/mouse serial devices, PCI BIOS access, display, and multiprocessor support. TempleOS may require manually supplied ATA/SATA I/O ports; no external network or cloud services are indicated.
Runtime: Tasks, Memory, and Core Services
The kernel provides the execution substrate for all interactive and compiled HolyC code: scheduler/task model, job execution, exception/debug support, heaps/paging, strings, hashes, and system configuration. Architectural anchors are Kernel/Sched.HC, Kernel/KTask.HC, Kernel/Mem/MemPag.HC, and Kernel/Mem/PageTables.HC. Higher layers call these kernel-resident facilities directly rather than crossing process or service boundaries typical of hosted OSes.
Storage and Filesystems
Block-device drivers feed a unified disk/file layer supporting TempleOS’s RedSea filesystem plus FAT and ISO media. The flow is physical ATA/CD/DVD access → block/cache/cluster logic → filesystem-specific directory/file operations → application-facing file APIs. Key boundaries: Kernel/BlkDev/DskATA.HC, Kernel/BlkDev/DskCache.HC, Kernel/BlkDev/FileSysRedSea.HC, Kernel/BlkDev/FileSysFAT.HC, and Kernel/BlkDev/FileSysISO.HC. User-facing mount, format, check, and file-manager operations sit in Adam/ABlkDev/Mount.HC and related modules.
HolyC Compiler and Self-Hosting
The native compiler lexes/parses HolyC, resolves symbols/assembly, applies optimization passes, and emits/loads executable code into the live OS environment. Its principal pipeline is represented by Compiler/Lex.HC, Compiler/PrsExp.HC, Compiler/BackA.HC, Compiler/AsmResolve.HC, and Compiler/CMain.HC. Compiler/Compiler.BIN is the supplied compiler binary; source and runtime are tightly coupled to the TempleOS environment.
Interactive Desktop and Document System
“Adam” is the high-level OS environment: windows, menus, controls, graphics, sound, autocomplete, and the DolDoc editor/document runtime. DolDoc documents (.DD) combine editable rich text with executable/code-oriented interactions. Main components include Adam/WinMgr.HC, Adam/Menu.HC, Adam/DolDoc/DocEd.HC, Adam/DolDoc/DocRun.HC, and Adam/Gr/GrInitA.HC. Input/control flow runs from kernel device input through window/control dispatch into documents and applications.
Applications, Content, and Distribution
Applications are in-tree HolyC programs launched through per-app Load.HC/Run.HC entry points, e.g. Apps/Psalmody/Run.HC, Apps/ToTheFront/Run.HC, and Apps/Budget/Run.HC. Demo/ provides executable examples and games, while Doc/ is the native documentation corpus. Install, boot-media, and distribution workflows are implemented in Misc/OSInstall.HC, Misc/DoDistro.HC, and Adam/Opt/Boot/MakeBoot.HC. Linux utilities such as Linux/TOSZ.CPP support archive/compression handling externally but do not provide a host compiler.
Main entry points: KMain.HC Kernel initialization · FileSysRedSea.HC RedSea, FAT, ISO filesystems · KLoad.HC Hardware devices · AsmResolve.HC Assembly resolution and codegen
Components 20
Boot and Kernel
- ISO / VM boot media · Bootable media contains the compressed self-hosted system.
- StartOS
StartOS.HC - Bootstrap kernel image
0000Boot/0000Kernel.BIN.C - 16/64-bit startup
Kernel/KStart64.HC - Kernel initialization · Initializes globals, tasks, interrupts, display, and devices.
Kernel/KMain.HC - Tasks and scheduler
Kernel/Sched.HC - Paging and heaps
Kernel/Mem/MemPag.HC - Hardware devices · ATA/CD/DVD, input, display, PCI BIOS, and multiprocessor support.
Kernel/KLoad.HC
Storage
- Block and cache layer
Kernel/BlkDev/DskCache.HC - RedSea, FAT, ISO filesystems
Kernel/BlkDev/FileSysRedSea.HC - Mount and disk tools
Adam/ABlkDev/Mount.HC
HolyC Runtime
- Supplied compiler binary · Loaded inside TempleOS; it is not a host build tool.
Compiler/Compiler.BIN - HolyC lexer and parser
Compiler/PrsExp.HC - Assembly resolution and codegen · Emits and loads executable code into the live OS.
Compiler/AsmResolve.HC
Adam Desktop
- Windows and controls
Adam/WinMgr.HC - DolDoc editor and runner · Editable documents combine rich text and executable interactions.
Adam/DolDoc/DocRun.HC
Apps and Distribution
- In-tree applications · Programs use per-application Load.HC and Run.HC entry points.
Apps/Psalmody/Run.HC - Docs and demos · Native documentation plus executable examples and games.
- Install and boot-media workflow
Misc/DoDistro.HC - Linux archive utility · Supports archive/compression handling only; it does not compile TempleOS.
Linux/TOSZ.CPP
Connections 22
- ISO / VM boot media → StartOS: boots
- StartOS → Bootstrap kernel image: loads
- Bootstrap kernel image → 16/64-bit startup: enters
- 16/64-bit startup → Kernel initialization: initializes
- Kernel initialization → Tasks and scheduler: starts
- Kernel initialization → Paging and heaps: configures
- Kernel initialization → Hardware devices: brings up
- Hardware devices → Block and cache layer: block I/O
- Block and cache layer → RedSea, FAT, ISO filesystems: serves blocks
- RedSea, FAT, ISO filesystems → Mount and disk tools: mounts and manages
- RedSea, FAT, ISO filesystems → Supplied compiler binary: loads
- Supplied compiler binary → HolyC lexer and parser: runs
- HolyC lexer and parser → Assembly resolution and codegen: parses HolyC
- Assembly resolution and codegen → Tasks and scheduler: loads live code into
- Hardware devices → Windows and controls: input and display
- Windows and controls → DolDoc editor and runner: hosts
- DolDoc editor and runner → HolyC lexer and parser: executes HolyC through
- Assembly resolution and codegen → In-tree applications: compiles and loads
- Windows and controls → In-tree applications: launches
- RedSea, FAT, ISO filesystems → Docs and demos: stores
- Install and boot-media workflow → ISO / VM boot media: creates
- Linux archive utility → Install and boot-media workflow: archives externally