redefine README.md

This commit is contained in:
2026-03-24 13:40:18 +00:00
parent 887564bb3a
commit 4e633163ce
7 changed files with 123 additions and 102 deletions
+30 -102
View File
@@ -1,129 +1,66 @@
# PROMETEU Runtime
# PROMETEU
PROMETEU é um **runtime educacional e experimental** inspirado em consoles clássicos,
com foco em **ensinar programação, arquitetura de sistemas e conceitos de hardware
através de software**.
Este repositório contém o **runtime do PROMETEU**, implementado em Rust, responsável por:
- simular um “hardware lógico” simples
- executar programas (futuros cartuchos) em um loop determinístico
- abstrair plataformas modernas (desktop, mobile, etc.) de forma consistente
PROMETEU é um **ecossistema educacional e experimental** inspirado em consoles clássicos, com foco em **ensinar programação, arquitetura de sistemas e conceitos de hardware através de software**.
> PROMETEU é uma máquina virtual simples, explícita e didática.
---
## 🎯 Objetivos do Runtime
## 🎯 Objetivos do Projeto
- Executar um loop fixo (60 Hz)
- Manter um framebuffer de baixa resolução (estilo console)
- Fornecer periféricos simples e determinísticos:
- GFX (framebuffer + double buffer)
- INPUT (D-Pad, botões)
- TOUCH (ponteiro absoluto, single-touch)
- Garantir **portabilidade total** entre plataformas
- Servir como base para ensino, game jams e experimentação
- **Simular um “hardware lógico” simples**: Criar uma barreira de entrada baixa para entender como computadores funcionam.
- **Loop Determinístico**: Garantir que o mesmo código produza o mesmo resultado em qualquer plataforma.
- **Portabilidade Total**: O núcleo não depende de sistema operacional, permitindo rodar de computadores modernos a hardware dedicado.
- **Ferramentas de Primeiro Nível**: Oferecer depuração e inspeção profunda como parte central da experiência.
---
## 🧠 Filosofia de Design
- **Sem magia**: tudo é explícito
- **Sem heurística implícita**: o runtime não “adivinha intenções”
- **Determinístico**: mesmo input → mesmo resultado
- **Hardware-first**: APIs modelam periféricos, não frameworks modernos
- **Portável por definição**: se não funciona em todas as plataformas, não existe
- **Sem magia**: tudo é explícito.
- **Sem heurística implícita**: o sistema não “adivinha intenções”.
- **Determinístico**: mesmo input → mesmo resultado.
- **Hardware-first**: APIs modelam periféricos, não frameworks modernos.
- **Portável por definição**: se não funciona em todas as plataformas, não existe.
---
## 📦 Estrutura do Projeto (Monorepo)
## 📦 Estrutura do Monorepo
Este repositório usa um **Cargo Workspace** (monorepo):
Este repositório é organizado como um workspace Rust e contém diversos componentes:
```
runtime/
Cargo.toml # Workspace root
rust-toolchain.toml # Versão do Rust (fixa)
crates/
prometeu/ # CLI Dispatcher (ponto de entrada unificado)
prometeu-core/ # PROMETEU Core (hardware lógico)
prometeu-runtime-desktop/ # Host desktop (janela, input real, present)
cart-demo/ # Cartucho/demo hardcoded (temporário)
```
### crates/prometeu
O binário principal que centraliza o acesso ao ecossistema:
- `prometeu run <cart>`: Executa um cartucho
- `prometeu debug <cart>`: Inicia em modo debug
- `prometeu build/pack`: Comandos planejados para ferramentas de build e empacotamento
### crates/prometeu-core
Contém o **núcleo do PROMETEU**:
- loop lógico
- periféricos
- framebuffer
- nenhuma dependência de sistema operacional
### crates/prometeu-runtime-desktop
Implementação de host para desktop:
- cria janela
- traduz teclado/mouse/touch do SO para o core
- apresenta o framebuffer na tela
### crates/cart-demo
Código de demonstração hardcoded.
Será substituído futuramente por:
- cartuchos
- bytecode
- scripts
---
## 🖥️ Plataformas
Atualmente:
- Desktop (primeiro alvo)
Planejado:
- Mobile
- Steam Deck
- Hardware dedicado (experimental, longo prazo)
- **[crates/](./crates)**: Implementação do software em Rust.
- **[prometeu](./crates/prometeu)**: Interface de linha de comando (CLI) unificada.
- **[prometeu-core](./crates/prometeu-core)**: O núcleo lógico, VM e SO interno.
- **[prometeu-runtime-desktop](./crates/prometeu-runtime-desktop)**: Host para execução em sistemas Desktop.
- **[docs/](./docs)**: Documentação técnica e especificações do sistema.
- **[devtools-protocol/](./devtools-protocol)**: Definição do protocolo de comunicação para ferramentas de desenvolvimento.
- **[test-cartridges/](./test-cartridges)**: Exemplos e suítes de teste de cartuchos.
---
## 🛠️ Requisitos
- Rust (via `rustup`)
- Toolchain definido em `rust-toolchain.toml`
Instalação do Rust:
```bash
rustup-init
```
- **Rust**: Versão definida em `rust-toolchain.toml`.
- **Instalação**: Use o [rustup](https://rustup.rs/) para instalar a toolchain necessária.
---
## ▶️ Como rodar
## ▶️ Início Rápido
Na raiz do repositório:
Para compilar o projeto completo:
```bash
cargo build
./target/debug/prometeu run <caminho_do_cartucho>
```
Ou diretamente via cargo:
Para rodar um cartucho de exemplo:
```bash
cargo run -p prometeu -- run <caminho_do_cartucho>
./target/debug/prometeu run test-cartridges/color-square
```
No início, o host apenas valida:
- loop 60 Hz
- execução do core
- estrutura do runtime
Para mais detalhes sobre como usar a CLI, veja o README de **[prometeu](./crates/prometeu)**.
---
@@ -131,12 +68,7 @@ No início, o host apenas valida:
⚠️ **Em estágio inicial (bootstrap)**
O foco atual é:
- validar arquitetura
- validar loop e periféricos
- manter simplicidade máxima
Nada aqui deve ser considerado API estável ainda.
Atualmente o foco é na estabilização da arquitetura do core e do protocolo de depuração. Nada aqui deve ser considerado uma API estável ainda.
---
@@ -148,9 +80,5 @@ Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICE
## ✨ Nota Final
PROMETEU é tanto um projeto técnico quanto pedagógico.
A ideia não é esconder complexidade,
mas **expor a complexidade certa**, no nível certo,
para que ela possa ser entendida, estudada e explorada.
PROMETEU é tanto um projeto técnico quanto pedagógico. A ideia não é esconder complexidade, mas **expor a complexidade certa**, no nível certo, para que ela possa ser entendida, estudada e explorada.