PROMETEU is an educational and experimental ecosystem inspired by classic consoles, focusing on teaching programming, system architecture, and hardware concepts through software.

PROMETEU is a simple, explicit, and educational virtual machine.

🎯 Project Goals

Simulate simple "logical hardware": Create a low entry barrier for understanding how computers work.
Deterministic Loop: Ensure the same code produces the same result on any platform.
Total Portability: The core does not depend on an operating system, allowing it to run from modern computers to dedicated hardware.
First-Class Tools: Offer deep debugging and inspection as a central part of the experience.

🧠 Design Philosophy

No magic: everything is explicit.
No implicit heuristics: the system doesn't "guess intentions".
Deterministic: same input → same result.
Hardware-first: APIs model peripherals, not modern frameworks.
Portable by definition: if it doesn't work on all platforms, it doesn't exist.

📦 Monorepo Structure

This repository is organized as a Rust workspace and contains several components:

crates/: Software implementation in Rust.
- prometeu: Unified command-line interface (CLI).
- prometeu-core: The logical core, VM, and internal OS.
- prometeu-runtime-desktop: Host for execution on Desktop systems.
docs/: Technical documentation and system specifications.
devtools-protocol/: Definition of the communication protocol for development tools.
test-cartridges/: Cartridge examples and test suites.

🛠️ Requirements

Rust: Version defined in rust-toolchain.toml.
Installation: Use rustup to install the required toolchain.

▶️ Quick Start

To compile the full project:

cargo build

To run an example cartridge:

./target/debug/prometeu run test-cartridges/color-square-ts

For more details on how to use the CLI, see the prometeu README.

🚧 Project Status

⚠️ Early stage (bootstrap)

Currently, the focus is on stabilizing the core architecture and debugging protocol. Nothing here should be considered a stable API yet.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

✨ Final Note

PROMETEU is both a technical and pedagogical project. The idea is not to hide complexity, but to expose the right complexity, at the right level, so it can be understood, studied, and explored.