diff --git a/README.md b/README.md index e136eaaf..44d726fa 100644 --- a/README.md +++ b/README.md @@ -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 `: Executa um cartucho -- `prometeu debug `: 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 ``` -Ou diretamente via cargo: +Para rodar um cartucho de exemplo: ```bash -cargo run -p prometeu -- run +./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. diff --git a/crates/prometeu-core/README.md b/crates/prometeu-core/README.md new file mode 100644 index 00000000..8def6834 --- /dev/null +++ b/crates/prometeu-core/README.md @@ -0,0 +1,14 @@ +# PROMETEU Core + +Este crate contém a biblioteca central que define o comportamento do hardware e software do PROMETEU. + +## Responsabilidades + +- **Hardware Lógico**: Definição de GFX, Input, Audio e Touch. +- **Máquina Virtual**: Execução de bytecode customizado (PBC - Prometeu Byte Code). +- **Virtual FS**: Gerenciamento de arquivos e acesso ao "cartucho". +- **Firmware/OS**: O sistema operacional interno que gerencia o ciclo de vida das aplicações, splash screens e o Hub Home. + +## Arquitetura + +O core é projetado para ser determinístico e portátil. Ele não faz chamadas diretas ao sistema operacional do host; em vez disso, define traços (traits) que os hosts devem implementar (ex: `FsBackend`). diff --git a/crates/prometeu-runtime-desktop/README.md b/crates/prometeu-runtime-desktop/README.md new file mode 100644 index 00000000..ba137893 --- /dev/null +++ b/crates/prometeu-runtime-desktop/README.md @@ -0,0 +1,18 @@ +# PROMETEU Desktop Runtime + +Esta é a implementação de host para plataformas desktop, permitindo que o PROMETEU rode em Windows, Linux e macOS. + +## Funcionalidades + +- **Renderização**: Utiliza a GPU via biblioteca `pixels` para apresentar o framebuffer de baixa resolução. +- **Input**: Traduz eventos de teclado e controle (via `winit`) para os sinais de hardware do PROMETEU. +- **Áudio**: Interface com o sistema de som do host (via `cpal`). +- **Debugging**: Hospeda um servidor TCP que implementa o **DevTools Protocol**, permitindo conexões de IDEs ou debuggers externos. + +## Como rodar + +Geralmente executado via CLI principal (`prometeu`), mas pode ser chamado diretamente para testes: + +```bash +cargo run -- --run path/to/cart +``` diff --git a/crates/prometeu/README.md b/crates/prometeu/README.md new file mode 100644 index 00000000..c09dcf71 --- /dev/null +++ b/crates/prometeu/README.md @@ -0,0 +1,14 @@ +# PROMETEU CLI (Dispatcher) + +O binário `prometeu` atua como o front-end unificado para o ecossistema. Ele não implementa a lógica de execução ou compilação, mas sabe onde encontrar os binários que as implementam. + +## Comandos + +- `prometeu run `: Executa um cartucho usando o runtime disponível. +- `prometeu debug [--port

]`: Inicia a execução em modo de depuração. +- `prometeu build `: (Planejado) Chama o compilador `prometeuc`. +- `prometeu pack `: (Planejado) Chama o empacotador `prometeup`. + +## Funcionamento + +O dispatcher localiza os binários irmãos (`prometeu-runtime`, `prometeuc`, etc.) no mesmo diretório onde ele próprio está instalado. Ele herda `stdin`, `stdout` e `stderr`, e propaga o código de saída do processo chamado. diff --git a/devtools-protocol/protocol.md b/devtools-protocol/README.md similarity index 88% rename from devtools-protocol/protocol.md rename to devtools-protocol/README.md index 8c91209f..ec6b01b5 100644 --- a/devtools-protocol/protocol.md +++ b/devtools-protocol/README.md @@ -6,6 +6,12 @@ Este documento descreve o protocolo de comunicação entre o Runtime do Prometeu O protocolo é baseado em JSON, enviado via uma conexão de transporte (geralmente TCP). Cada mensagem é um objeto JSON em uma única linha (JSONL). +## Estrutura + +- **[protocol.json](./protocol.json)**: Definição formal do protocolo em formato JSON. +- **[protocol.md](README.md)**: Documentação legível para humanos descrevendo os comandos, eventos e tipos. +- **[examples/](./examples)**: Exemplos de fluxos de mensagens (handshake, breakpoints, etc.) em formato JSONL. + ## Versionamento O protocolo possui uma versão explícita definida no campo `protocol_version`. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..30546631 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +# PROMETEU Documentation + +Este diretório contém a documentação técnica e especificações do projeto PROMETEU. + +## Conteúdo + +### 📜 [Especificações (Specs)](./specs) +Documentação detalhada sobre a arquitetura do sistema, formato de cartuchos, conjunto de instruções da VM e muito mais. +- [Índice de Tópicos](./specs/topics/table-of-contents.md) + +### 🐞 [Debugger](./debugger) +Documentação sobre as ferramentas de depuração e como integrar novas ferramentas ao ecossistema. + +### 🔌 [DevTools Protocol](../devtools-protocol) +Definição do protocolo de comunicação utilizado para depuração e inspeção em tempo real. diff --git a/test-cartridges/README.md b/test-cartridges/README.md new file mode 100644 index 00000000..af67fa3e --- /dev/null +++ b/test-cartridges/README.md @@ -0,0 +1,26 @@ +# PROMETEU Test Cartridges + +Este diretório contém cartuchos de exemplo e suítes de teste para validar o comportamento do runtime e das ferramentas de desenvolvimento do PROMETEU. + +## Cartuchos Disponíveis + +### 🟩 [color-square](./color-square) +Um cartucho simples que demonstra: +- Inicialização do sistema. +- Renderização de um quadrado colorido no framebuffer. +- Loop básico de execução. + +## Estrutura de um Cartucho + +Um cartucho PROMETEU (em sua forma descompactada) geralmente consiste em: +- `manifest.json`: Metadados do aplicativo (ID, título, versão, modo). +- `program.pbc`: O bytecode compilado para a VM do PROMETEU. +- `assets/`: Recursos como tiles, sprites e amostras de áudio. + +## Como usar + +Você pode rodar qualquer um destes cartuchos usando a CLI principal: + +```bash +prometeu run test-cartridges/ +```