bquarkz
0e6da1433b
Co-authored-by: Nilton Constantino <nilton.constantino@visma.com> Reviewed-on: #5
85 lines
2.7 KiB
Markdown
85 lines
2.7 KiB
Markdown
# PROMETEU
|
|
|
|
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/](./crates)**: Software implementation in Rust.
|
|
- **[prometeu](./crates/prometeu)**: Unified command-line interface (CLI).
|
|
- **[prometeu-core](./crates/prometeu-core)**: The logical core, VM, and internal OS.
|
|
- **[prometeu-runtime-desktop](crates/prometeu-runtime-desktop)**: 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**: Version defined in `rust-toolchain.toml`.
|
|
- **Installation**: Use [rustup](https://rustup.rs/) to install the required toolchain.
|
|
|
|
---
|
|
|
|
## ▶️ Quick Start
|
|
|
|
To compile the full project:
|
|
|
|
```bash
|
|
cargo build
|
|
```
|
|
|
|
To run an example cartridge:
|
|
|
|
```bash
|
|
./target/debug/prometeu run test-cartridges/color-square
|
|
```
|
|
|
|
For more details on how to use the CLI, see the **[prometeu](./crates/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](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.
|
|
|