PROMETEU Runtime

PROMETEU is an educational and experimental fantasy handheld / fantasy console. This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, host integration, CLI entrypoints, development utilities, specs, and discussion artifacts.

The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish:

machine-level specs;
VM/runtime internal architecture;
implementation crates;
discussion workflow and lessons learned.

What This Repository Contains

crates/console/: core machine/runtime crates such as prometeu-vm, prometeu-system, prometeu-hal, prometeu-drivers, and prometeu-firmware
crates/host/: host-side execution surfaces, currently including prometeu-host-desktop-winit
crates/tools/: user-facing and support binaries such as prometeu and pbxgen-stress
crates/dev/: test support, layer tests, and quality-check utilities
docs/specs/runtime/: canonical PROMETEU machine specs
docs/vm-arch/: canonical VM/runtime architecture and ISA references
devtools/: debugger protocol material
discussion/: agendas, decisions, plans, and lessons for architectural work
test-cartridges/: cartridge fixtures used for validation and manual runs

Canonical Documentation

Use these entrypoints instead of inferring the model from isolated source files:

Machine specs: authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI
VM architecture: authoritative internal architecture for VM/runtime invariants
ISA reference: bytecode-level instruction set authority
Discussion workflow: architectural agenda, decision, and execution traceability

Workspace Layout

This repository is a Rust workspace rooted at Cargo.toml with members in:

crates/console
crates/host
crates/tools
crates/dev

The main user-facing dispatcher binary is prometeu, built from crates/tools/prometeu-cli.

Current CLI surface:

prometeu run <cart>
prometeu debug <cart> --port <port>
prometeu build <project-dir>
prometeu pack <cart-dir>
prometeu verify ...

Not every command is fully implemented in every distribution path yet. Today, the runtime flow is the most concrete and the dispatcher forwards execution to specialized binaries when they are available.

Requirements

Rust toolchain from rust-toolchain.toml
rustup for toolchain installation and management

Quick Start

Build the workspace:

cargo build

Inspect the CLI:

cargo run -q -p prometeu-cli --bin prometeu -- --help

Run the current stress cartridge fixture:

cargo run -q -p prometeu-cli --bin prometeu -- run test-cartridges/stress-console

The desktop runtime opens a native window through the host layer, so this last command is intended for a local graphical environment.

Current State

The project is still in active architectural and implementation convergence.

the machine contract is being clarified through the specs and discussion workflow;
the workspace already contains concrete runtime and host code;
some CLI subcommands still act as dispatcher placeholders for binaries that are not always present in a local build or distribution.

Treat APIs, file formats, and execution flows as evolving unless the relevant spec explicitly defines them as stable.

License

This project is licensed under the MIT License.

3.6 KiB Raw Blame History