Skip to content

SOURCE-TREE.md

Latest commit

 

History

History
181 lines (145 loc) · 5.96 KB

SOURCE-TREE.md

File metadata and controls

181 lines (145 loc) · 5.96 KB
Raw

Source tree

The publication source is organized by software responsibility while every assembled image retains exact historical address order. These are different views of the same reconstruction:

  • directories answer what subsystem owns this code or data?;
  • top-level image roots answer which bytes appear, and in what order?

Start with ../src/README.md, then use the local README in the subsystem being studied.

Complete tree

src/
├── README.md
├── platform/
│   └── zx-spectrum/
│       ├── README.md
│       └── rom.inc
├── desktop/
│   ├── installer/
│   │   ├── README.md
│   │   ├── images/                 loaded, decoded and transient-menu roots
│   │   ├── stage1/                 protected symbol decoder and tables
│   │   ├── stage2/                 relocation and packet-stream expansion
│   │   ├── menu/                   universal installer runtime and UI
│   │   └── stored-frontends/
│   │       ├── producers/          logical-origin installable payloads
│   │       └── records/            physical transient-menu wrappers
│   └── editor/
│       ├── README.md
│       ├── core/
│       │   ├── README.md
│       │   ├── abi/
│       │   ├── startup/
│       │   ├── document/
│       │   ├── commands/
│       │   ├── editing/
│       │   ├── layout/
│       │   ├── pictures/
│       │   ├── rendering/
│       │   ├── tape/
│       │   └── workspaces/
│       ├── output/
│       │   ├── README.md
│       │   ├── common/
│       │   ├── devices/
│       │   └── transports/
│       ├── extensions/
│       │   └── installed-fonteditor/
│       │       └── README.md
│       ├── image-layout/           canonical physical composition fragments
│       └── images/
│           └── README.md
└── utilities/
    ├── README.md
    ├── fonteditor/
    │   └── README.md
    ├── convertor/
    │   └── README.md
    └── screentop/
        └── README.md

Image roots are the physical authority

For every binary target, a top-level .asm file establishes ORG, selects constants and includes modules in ascending historical address order. Important roots are:

src/desktop/installer/images/loaded.asm
src/desktop/installer/images/decoded.asm
src/desktop/installer/images/menu.asm
src/desktop/editor/images/**/*.asm
src/utilities/fonteditor/standalone_fonteditor_packed.asm
src/utilities/fonteditor/standalone_fonteditor_unpacked.asm
src/utilities/convertor/convertor_protected_basic.asm
src/utilities/convertor/standalone_convertor_runtime.asm
src/utilities/screentop/standalone_screentop_unpacked.asm

Directory order must never be substituted for these include sequences.

Universal installer

The installer has three exact lifecycle images:

loaded protected image
    -> first decoded image
    -> relocated/expanded transient menu
    -> selected installed editor

Stored front ends deliberately have two source contexts:

  • producers/ assembles bytes at their future logical destination;
  • records/ embeds the same bytes at their physical menu-storage address.

Behavior belongs to the producer or shared output module. Storage placement belongs to the record wrapper.

Resident editor

The installed editor is composed from adjacent responsibilities:

low entries
+ persistent document/picture arena
+ selected output subsystem or extension
+ fixed public ABI
+ shared editor core

src/desktop/editor/image-layout/core-body.inc is the single canonical $BC55-$E667 module order. Every installed image and the transient installer reuse it.

The editor core is divided by responsibility, not by disassembly history. Local README files provide both the exact module table and a conceptual reading path through lifecycle, document transactions, layout, rasterization and tape recovery.

Output subsystem

A normal Epson/K6304 configuration composes:

device protocol front end
+ named connection profile
+ reusable physical transport

BT100 and Gamacentrum own device-specific profiles because their connection records patch protocol logic. XY 4150, Minigraf and Alfi are self-contained devices. Complete roots under editor/images/ select these layers without copying their implementation.

Standalone utilities

Each utility preserves a lifecycle-specific top-level image and divides the expanded implementation into semantic chapters:

  • FONTEDITOR — protected expansion, screen/title editor and proportional editor;
  • CONVERTOR — protected loader, normalization, in-place expansion and backwards DESKTOP serialization;
  • SCREENTOP — relocated bootstrap, large-canvas editor, floating windows and self-extracting tape packer.

Immutable compressed streams, screen images, fonts and seeds remain binary data assets. Identified executable intervals are assembler source.

Source conventions

The source uses descriptive global labels and dot-prefixed local labels. Names ending in _operand, _instruction or _opcode identify mutable bytes in executable instructions. These are runtime state fields, not disassembler noise.

Module introductions and routine contracts describe:

  • the active memory representation;
  • register and stack entry/exit state;
  • publication boundaries;
  • self-modifying writers and readers;
  • known malformed-input or masked-failure behavior.

Verification

Run from the repository root:

python3 tools/verify_source_readmes.py
python3 tools/verify.py

The first command audits all source-local README files and their relative links. The second assembles every image, checks established fingerprints, rebuilds the complete 43-pair distribution tape and verifies all direct runtime tapes.