feat(run): abre o Java da placa real e guarda dados no clone

Linux, WSL e Windows usam o mesmo run --all, e plugins, cache e logs ficam em .pitiupi na raiz do projeto. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-03 23:52:08 -03:00
1 parent 22540eaffb
commit e84aba2f4e
@@ -10,7 +10,7 @@
 | D6 | Mensagens `Serializable` em `byte[]` | Independência do transporte; plugins definem tipos | [07_mensagens_e_serializacao.md](documentation/07_mensagens_e_serializacao.md) |
 | D7 | Plugins via JAR + Java SPI | Carregamento dinâmico sem recompilar o núcleo | [09_sistema_de_plugins.md](documentation/09_sistema_de_plugins.md) |
 | D8 | Classloader por JAR de plugin | Isolar dependências; desserialização com `PluginObjectInputStream` | [09_sistema_de_plugins.md](documentation/09_sistema_de_plugins.md) |
-| D9 | Plugins em `PITIUPI_HOME/plugins` | Dados do usuário fora do clone Git; `PITIUPI_HOME` ou `~/pitiupi` | [00_quickstart.md](documentation/00_quickstart.md) |
+| D9 | Plugins em `PITIUPI_HOME/plugins` | Dados de execução em `.pitiupi/` na raiz do clone (não versionado). `PITIUPI_HOME` ainda pode apontar outro diretório | [00_quickstart.md](documentation/00_quickstart.md) |
 | D10 | Erros com `ErrorCode` | Mensagens PT na UI; `PitiupiException` no domínio | [13_guia_desenvolvimento.md](documentation/13_guia_desenvolvimento.md) |
 | D11 | Reinício após instalar/remover JAR | Mutar `plugins/` exige reiniciar o app para recarregar SPI | [04_inicializacao_e_gui.md](documentation/04_inicializacao_e_gui.md) |
 | D16 | UI em abas; sem `JFrame` de plugin | Conteúdo na `MainShellFrame`; galeria e peer actions abrem abas | [04_inicializacao_e_gui.md](documentation/04_inicializacao_e_gui.md) |
@@ -27,5 +27,6 @@
 | D27 | TTL padrão 1, ajustável de 1 a 32 | 1 permanece na sub-rede local; valor maior é opção de configuração | [appendix_portas_e_multicast.md](documentation/appendix_portas_e_multicast.md) |
 | D28 | Saída Automático, Cabo ou Wi-Fi | Multicast, IP exibido e TCP de saída usam a interface escolhida | [appendix_portas_e_multicast.md](documentation/appendix_portas_e_multicast.md) |
 | D29 | Connect TCP com prazo de 5 s fora da EDT | Aviso só enquanto não há socket aberto para aquele IP | [06_tcp_conexoes.md](documentation/06_tcp_conexoes.md) |
+| D30 | `eth*` continua cabo, inclusive no WSL | A placa Wi-Fi do Windows não existe no Linux do WSL; reclassificar `eth` quebraria o Ubuntu nativo. Na sala o processo é o Java do Windows ou o Ubuntu instalado na máquina | [appendix_portas_e_multicast.md](documentation/appendix_portas_e_multicast.md) |

 Novas decisões: adicionar linha nesta tabela e detalhar no arquivo técnico correspondente.
@@ -1,24 +1,73 @@
 # Quickstart

-## Pré-requisitos
+O `run --all` compila o núcleo, os plugins do catálogo e abre a janela. Plugins, cache e logs ficam em **`.pitiupi/`** na pasta do projeto. JDK **17 ou superior** (`java` e `javac`) e Apache Ant. O script do Linux também usa `python3`.

- **JDK completo** (`java` e `javac`) — **Java 17 ou superior** (17, 21 ou 25). Núcleo e plugins compilam com `javac.source/target=17`.
- Apache Ant (`pitiupi`, `plugins/chat`, `plugins/screencast`)
+## Linux (Ubuntu instalado na máquina)

-Ubuntu / WSL:
+Abra o terminal, entre na pasta do projeto e rode:

 ```bash
-sudo apt install openjdk-21-jdk ant
-# ou: openjdk-17-jdk
-which javac ant
+sudo apt install openjdk-21-jdk ant python3
+chmod +x scripts/pitiupi.sh
+./scripts/pitiupi.sh run --all
 ```

-## Build
+A janela é a do Java do Linux. Cabo e Wi-Fi são as placas deste computador.

-Na raiz do clone:
+## Windows
+
+Abra o **Prompt de Comando**: tecla Windows, digite `cmd` e pressione Enter. Entre na pasta em que o projeto foi baixado e rode:
+
+```bat
+cd %USERPROFILE%\Downloads\pitiupi
+scripts\pitiupi.cmd run --all
+```
+
+Se a pasta for outra, troque o `cd`. No PowerShell o comando é o mesmo: `scripts\pitiupi.cmd run --all`.
+
+`java`, `javac` e `ant` precisam estar no PATH. No PowerShell, o JDK:
+
+```powershell
+winget install Microsoft.OpenJDK.17
+```
+
+O Apache Ant é o zip de <https://ant.apache.org/bindownload.cgi>: extraia e acrescente a pasta `bin` ao PATH. Feche o cmd e abra de novo.
+
+A janela é a do Java do Windows. Cabo e Wi-Fi são as placas deste computador.
+
+## WSL
+
+Abra o **Ubuntu** do WSL, não o cmd. Entre na pasta do projeto e use o comando do Linux:
+
+```bash
+sudo apt install openjdk-21-jdk ant python3
+chmod +x scripts/pitiupi.sh
+./scripts/pitiupi.sh run --all
+```
+
+Se o projeto foi baixado no Windows, por exemplo em Downloads:
+
+```bash
+cd /mnt/c/Users/SEU_USUARIO/Downloads/pitiupi
+chmod +x scripts/pitiupi.sh
+./scripts/pitiupi.sh run --all
+```
+
+A compilação usa o `javac` e o `ant` do Ubuntu. A janela abre no Windows, com as placas reais, então o JDK 17 do Windows também precisa estar instalado (`winget install Microsoft.OpenJDK.17` no PowerShell). Abrir o `java` de dentro do WSL, sem esse comando, não mostra o Wi-Fi do Windows. O motivo está em [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md).
+
+## Depois que a janela abrir
+
+Login com nome e porta (na sala, em geral `5000` nos dois). Abra plugins pela aba **Plugins**. Clique em **Todos** ou em um peer na lista lateral para ver as ações de cada plugin.
+
+Validação rápida do núcleo: `cd pitiupi && ant test`.
+
+## Build sem abrir a janela
+
+No Linux ou no WSL, na pasta do projeto:

 ```bash
 ./scripts/pitiupi.sh build --all
+./scripts/pitiupi.sh link --all
 ```

 Ou manualmente:
@@ -28,21 +77,3 @@ cd pitiupi && ant jar
 cd plugins/chat && ant jar
 cd plugins/screencast && ant jar
 ```
-
-## Instalar plugins
-
-Runtime: JARs em **`PITIUPI_HOME/plugins`** (padrão `~/pitiupi/plugins`).
-
-```bash
-./scripts/pitiupi.sh link --all
-```
-
-## Executar
-
-```bash
-./scripts/pitiupi.sh run --all
-```
-
-Login com nome e porta; abra plugins pela aba **Plugins**. Clique em **Todos** ou em um peer na lista lateral para ver ações de cada plugin.
-
-Validação rápida do núcleo: `cd pitiupi && ant test`.
@@ -52,7 +52,7 @@ cd plugins/chat && ant clean jar
 ./scripts/pitiupi.sh link --all
 ```

-Isso recria o symlink `~/pitiupi/plugins/chat.jar` → o JAR buildado. O comando `link` lista o destino real de cada `.jar`.
+Isso recria o symlink `.pitiupi/plugins/chat.jar` → o JAR buildado, na raiz do clone. O comando `link` lista o destino real de cada `.jar`.

 # Interface gráfica

@@ -111,4 +111,4 @@ sequenceDiagram
    PM->>UI: receiveMessage no plugin
 ```

-**Falhas comuns:** firewall bloqueando UDP na porta do login; portas diferentes entre peers; isolamento de clientes no Wi‑Fi; WSL num lado e Windows nativo no outro.
+**Falhas comuns:** firewall bloqueando UDP na porta do login; portas diferentes entre peers; isolamento de clientes no Wi‑Fi; um processo dentro do WSL e o outro no Java do Windows. Onde abrir a janela: [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md).
@@ -45,7 +45,7 @@ Depois, para runtime local:

 ## Testes manuais — dois PCs (mesma Wi‑Fi)

-Mesma **porta** em ambos (ex. 5000), **mesmos JARs** em `~/pitiupi/plugins` em cada máquina:
+Mesma **porta** em ambos (ex. 5000), **mesmos JARs** em `.pitiupi/plugins` na raiz do clone de cada máquina:

 - [ ] Presença e linha **Todos**
 - [ ] Troca de mensagens no chat (multicast e, se possível, unicast/TCP)
@@ -35,11 +35,15 @@ Substitua `5000` e o IP do colega pelos valores da aba Configurações.
 - Caminho: `traceroute IP` ou `tracepath IP`. Conte os saltos até o IP do colega: esse número é o TTL mínimo.
 - Porta TCP do aplicativo: `nc -vz -w 3 IP 5000` (ou `ncat`)

+## WSL na sala
+
+Cada um abre o programa pelo caso da própria máquina, descrito no [quickstart](00_quickstart.md). No Linux, o terminal e `./scripts/pitiupi.sh run --all` (Java do Linux). No Windows, o cmd e `scripts\pitiupi.cmd run --all` (Java do Windows). No WSL, o terminal do Ubuntu e `./scripts/pitiupi.sh run --all` (a janela abre no Java do Windows). Os dois lados se veem. Abrir o `java` de dentro do WSL, sem esse comando, mostra só `eth0` ou `eth1`. Detalhe: [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md).
+
 ## Como ler o resultado

 - **O ping falha.** O problema está na rede entre os PCs: sub-rede diferente, cabo, Wi-Fi ou isolamento de clientes no roteador. O Pitiupi não contorna isso.
 - **O ping funciona e a porta TCP não abre.** Firewall, porta errada ou o outro Pitiupi não está escutando. Confira a porta na aba Configurações e libere UDP e TCP nessa porta.
- **O ping com TTL 1 responde e a lista só mostra Todos.** A descoberta é multicast, e um TTL baixo não é a causa quando o `tracert` tem um salto só. Confira porta igual, a mesma saída (os dois no cabo ou os dois no Wi-Fi; `169.254` e `192.168` ao mesmo tempo não se veem), firewall de UDP e isolamento de clientes. Um lado no WSL e o outro no Windows costuma impedir o multicast: os dois peers precisam estar no mesmo tipo de ambiente.
+- **O ping com TTL 1 responde e a lista só mostra Todos.** A descoberta é multicast, e um TTL baixo não é a causa quando o `tracert` tem um salto só. Confira porta igual, a mesma saída (os dois no cabo ou os dois no Wi-Fi; `169.254` e `192.168` ao mesmo tempo não se veem), firewall de UDP e isolamento de clientes. Um processo aberto dentro do WSL e o outro no Java do Windows não compartilham a mesma placa: os dois precisam estar no Java do Windows ou os dois no Ubuntu instalado na máquina. Ver [appendix_portas_e_multicast.md](appendix_portas_e_multicast.md).
 - **O `tracert` tem mais de um salto e a lista fica vazia.** Suba o TTL em Configurações até o número de saltos (máximo 32) e aplique nos dois. Um roteador no meio só entrega o multicast se estiver disposto a encaminhar o grupo.
 - **O colega está na lista e o TCP avisa que não conectou.** A tentativa de abrir o socket espera no máximo cerca de **5 s** e a janela continua utilizável. Veja firewall de TCP ou se a porta mudou no meio do caminho.

@@ -24,12 +24,32 @@ Execute duas instâncias com **portas diferentes** (ex.: 5000 e 5001). Mesmo nom
 - Bloqueio de multicast em redes de visitantes ou isolamento AP→AP impede descoberta.
 - Em laboratório, preferir cabo ou Wi‑Fi com multicast habilitado.

-## WSL2
+## Onde o processo Java roda

-Executar o Pitiupi no WSL e peers no Windows (ou vice-versa) pode falhar em multicast. Preferir:
+A aba **Configurações** só lista interfaces que **este** processo enxerga. O nome decide a família: `eth`, `eno`, `enp`, `ens` ou “Ethernet” é **Cabo**; `wlan`, `wlp` ou “Wi-Fi” é **Wi-Fi**. O clone Git pode ficar no disco do WSL ou numa pasta do Windows. O que muda a lista é qual `java` abre o JAR.

- todos os peers no mesmo ambiente (Linux nativo ou VMs), ou
- dois PCs físicos na mesma sub-rede.
+| Processo | O que a saída mostra |
+| --- | --- |
+| `java.exe` do Windows | Placas reais. Sem cabo com IPv4, **Cabo** não é oferecido. **Wi-Fi** aparece quando a placa sem fio está ligada. |
+| Ubuntu instalado no PC (não é WSL) | `wlan*` e `eth*`/`enp*` reais. O mesmo `./scripts/pitiupi.sh run --all` abre o Java do Linux. |
+| Java de dentro do WSL | Em geral uma interface virtual `eth0` ou `eth1`. O programa classifica isso como **Cabo**, mesmo com o cabo físico desconectado e o Windows no Wi-Fi. Não existe `wlan` nesse Linux, então a saída **Wi-Fi** não aparece. |
+
+Dois arranjos de WSL, e nenhum dos dois substitui o Java do Windows na sala:
+
+- **NAT** (IP `172.x` no `ip -4 addr`): o Linux não está na rede dos colegas. Quem está em `192.168.x` ou `169.254.x` não recebe o multicast. Aumentar o TTL não coloca esse processo na LAN.
+- **Rede espelhada** (o `eth*` mostra o mesmo IPv4 do Wi-Fi do Windows, por exemplo `192.168.3.x`): o rótulo **Cabo** segue o nome Linux, não o cabo da tomada. O socket ainda é o da interface virtual. A descoberta não é a mesma de um colega que abriu o Java no Windows.
+
+Não dá para o código “pegar a placa Wi-Fi do Windows” a partir do WSL: essa placa não está no espaço de rede do Linux. Tratar todo `eth*` como Wi-Fi quebraria o Ubuntu nativo, em que `eth` é cabo de verdade. Por isso a sala usa o mesmo tipo de processo nos dois lados: os dois no Java do Windows, ou os dois no Ubuntu instalado na máquina. Não misture um Pitiupi aberto no WSL com outro aberto no Windows.
+
+O passo a passo de cada máquina está no [quickstart](00_quickstart.md).
+
+| Onde a pessoa está | O que abrir | Comando, na pasta do projeto |
+| --- | --- | --- |
+| Linux (Ubuntu na máquina) | Terminal | `./scripts/pitiupi.sh run --all` — Java do Linux |
+| Windows | Prompt de Comando (`cmd`) | `scripts\pitiupi.cmd run --all` — Java do Windows |
+| WSL | Terminal do Ubuntu | `./scripts/pitiupi.sh run --all` — a janela abre no Java do Windows |
+
+No PowerShell o comando é o mesmo do cmd. Plugins, cache e logs ficam em `.pitiupi/` na pasta do projeto. JDK 17 do Windows, se faltar: `winget install Microsoft.OpenJDK.17`. No Windows o Ant também precisa estar no PATH.

 ## Escolha de interface (multicast)

@@ -118,7 +118,7 @@ O envio fica nos botões do painel.
 ## Passo 7 — Instalar e testar

 1. `ant jar` → `dist/pitiupi.ping.jar`.
-2. Aba **Configurações** → **Instalar JAR…** (ou copie para `~/pitiupi/plugins/`).
+2. Aba **Configurações** → **Instalar JAR…** (ou copie para `.pitiupi/plugins/` na raiz do clone).
 3. **Reinicie** o Pitiupi (obrigatório após mudar plugins).
 4. Dois processos no mesmo PC: portas **5000** e **5001**, nomes diferentes.
 5. Lista lateral → **Enviar ping para esta pessoa** → aba `↑` com IP; clique **Enviar ping** → RTT no log.