diff --git a/README.md b/README.md index 29489374..ad0f6ed4 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,94 @@ -# PROMETEU +# PROMETEU Runtime -PROMETEU is an **educational and experimental fantasy handheld / fantasy console ecosystem** inspired by classic consoles, focusing on **teaching programming, system architecture, and hardware concepts through software**. +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. -> PROMETEU is a fantasy console with a simple, explicit, and educational VM/runtime inside it. +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. -## 🎯 Project Goals +## What This Repository Contains -- **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. -- **DIY hardware affinity**: Keep the machine model close enough to handheld/console-era hardware that it can inform real embedded and homebrew-style implementations. +- `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 -## 🧠 Design Philosophy +Use these entrypoints instead of inferring the model from isolated source files: -- **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. -- **Console-era sensibility**: PROMETEU carries intentional influence from NES, SNES, Mega Drive, Game Boy, GBA, CPS-2, and adjacent DIY-friendly hardware thinking. +- [Machine specs](docs/specs/runtime/README.md): authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI +- [VM architecture](docs/vm-arch/ARCHITECTURE.md): authoritative internal architecture for VM/runtime invariants +- [ISA reference](docs/vm-arch/ISA_CORE.md): bytecode-level instruction set authority +- [Discussion workflow](discussion/index.ndjson): architectural agenda, decision, and execution traceability -## 🧭 Canonical Architecture +## Workspace Layout -PROMETEU is the machine. The VM/runtime is one subsystem inside that machine. +This repository is a Rust workspace rooted at [Cargo.toml](Cargo.toml) with members in: -Authoritative documents: +- `crates/console` +- `crates/host` +- `crates/tools` +- `crates/dev` -- [`docs/runtime/virtual-machine/ARCHITECTURE.md`](docs/vm-arch/ARCHITECTURE.md) is normative for VM/runtime invariants. -- [`docs/runtime/specs/README.md`](docs/specs/runtime/README.md) describes the broader PROMETEU machine, hardware model, and fantasy console context. -- Supporting material under `docs/` may expand, explain, or propose changes, but it must not silently collapse the whole machine into the VM layer. +The main user-facing dispatcher binary is `prometeu`, built from `crates/tools/prometeu-cli`. ---- +Current CLI surface: -## 📦 Monorepo Structure +- `prometeu run ` +- `prometeu debug --port ` +- `prometeu build ` +- `prometeu pack ` +- `prometeu verify ...` -This repository is organized as a Rust workspace and contains several components: +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. -- **[crates/](./crates)**: Software implementation in Rust. - - **[prometeu](crates/tools/prometeu)**: Unified command-line interface (CLI). - - **[prometeu-drivers](crates/console/prometeu-drivers)**: The virtual hardware (GPU, SPU, Input). - - **[prometeu-host-desktop-winit](crates/host/prometeu-host-desktop-winit)**: Host for execution on Desktop systems. -- **[docs/](./docs)**: Technical documentation and system specifications. -- **[devtools-protocol/](devtools)**: Definition of the communication protocol for development tools. -- **[test-cartridges/](./test-cartridges)**: Cartridge examples and test suites. +## Requirements ---- +- Rust toolchain from [rust-toolchain.toml](rust-toolchain.toml) +- `rustup` for toolchain installation and management -## 🛠️ Requirements +## Quick Start -- **Rust**: Version defined in `rust-toolchain.toml`. -- **Installation**: Use [rustup](https://rustup.rs/) to install the required toolchain. - ---- - -## ▶️ Quick Start - -To compile the full project: +Build the workspace: ```bash cargo build ``` -To run an example cartridge: +Inspect the CLI: ```bash -./target/debug/prometeu run test-cartridges/color-square-ts +cargo run -q -p prometeu-cli --bin prometeu -- --help ``` -For more details on how to use the CLI, see the **[prometeu](crates/tools/prometeu)** README. +Run the current stress cartridge fixture: ---- +```bash +cargo run -q -p prometeu-cli --bin prometeu -- run test-cartridges/stress-console +``` -## 🚧 Project Status +The desktop runtime opens a native window through the host layer, so this last command is intended for a local graphical environment. -⚠️ **Early stage (bootstrap)** +## Current State -Currently, the focus is on stabilizing the core architecture and debugging protocol. Nothing here should be considered a stable API yet. +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. -## 📜 License +Treat APIs, file formats, and execution flows as evolving unless the relevant spec explicitly defines them as stable. -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +## License ---- - -## ✨ 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. +This project is licensed under the [MIT License](LICENSE).