bQUARKz
affd0eb118
All checks were successful
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
95 lines
3.6 KiB
Markdown
95 lines
3.6 KiB
Markdown
# 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](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
|
|
|
|
## Workspace Layout
|
|
|
|
This repository is a Rust workspace rooted at [Cargo.toml](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](rust-toolchain.toml)
|
|
- `rustup` for toolchain installation and management
|
|
|
|
## Quick Start
|
|
|
|
Build the workspace:
|
|
|
|
```bash
|
|
cargo build
|
|
```
|
|
|
|
Inspect the CLI:
|
|
|
|
```bash
|
|
cargo run -q -p prometeu-cli --bin prometeu -- --help
|
|
```
|
|
|
|
Run the current stress cartridge fixture:
|
|
|
|
```bash
|
|
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](LICENSE).
|