redefine README.md
This commit is contained in:
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user