⚙️ Setup inicial

Do zero ao cargo run -p paebiru-node em 15 minutos se você está em Linux x86_64 com Nix. Outras plataformas exigem instalação manual das deps de sistema.

Caminho 1 — Nix (recomendado)

Obtém todo o toolchain: Rust nightly, TPM2-TSS, libbpf, CUDA opcional, cross-compile para RISC-V e Cortex-M, Python, Node, Zig, PHP, R, Ruby, .NET 8, JDK 17, Dart, Go. Reproduzível bit-a-bit entre máquinas.

Pré-requisitos

Nix com flakes habilitados.
~3 GB de espaço em disco para o shell.

Comando único

git clone https://github.com/paebiru/paebiru.git
cd paebiru
nix develop               # entra no shell
make build                # build do workspace default
make test                 # roda a suíte

Ao entrar no shell você verá:

🌿 Bem-vindo ao ambiente de desenvolvimento PAEBIRU (Nix)
Rust: rustc 1.86.0-nightly (...)
TPM2-TSS e Vulkan configurados.

Dica (CI): use nix develop --command bash -c 'make pre-commit' em scripts de CI.

Caminho 2 — Manual (Debian / Ubuntu 24.04)

Use este caminho se você não pode instalar Nix. Leva ~30 min.

1. Dependências de sistema

sudo apt-get update
sudo apt-get install -y \
    build-essential git curl pkg-config \
    libbpf-dev clang llvm libtss2-dev libssl-dev \
    cmake

2. Rust (nightly)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"
rustup toolchain install nightly --profile minimal
rustup component add rust-src rust-analyzer llvm-tools-preview clippy rustfmt
rustup target add riscv32imc-unknown-none-elf \
                thumbv7em-none-eabihf \
                wasm32-unknown-unknown

O rust-toolchain.toml na raiz fixa a versão exata do nightly. Não instale stable — o projeto usa Edition 2024 + features instáveis (no_std em MCUs).

3. Ferramentas Cargo

cargo install cargo-llvm-cov cargo-audit cargo-fuzz

4. Pre-commit

pip install pre-commit mdbook mdbook-mermaid
pre-commit install

5. Verificação

make check       # cargo check rápido
make test        # roda a suíte
make pre-commit  # hooks locais

Caminho 3 — macOS

brew install git pkg-config openssl@3 bpfcc libbpf llvm tpm2-tss
# ...em seguida o mesmo rustup/cargo install do caminho 2

macOS não suporta eBPF/XDP nativo. O Portão 1 (Load Shedder) é automaticamente desabilitado na detecção do Darwin; em produção, use um nó Linux como edge.

Caminho 4 — Windows (WSL2 recomendado)

A matriz de release é Linux-first. Windows é suportado via WSL2 (Ubuntu 24.04). O caminho nativo é experimental.

wsl --install -d Ubuntu-24.04
wsl
# dentro do WSL2, siga o Caminho 1 (Nix) ou 2 (manual)

Variáveis de ambiente

Variável	Default	Significado
`PAEBIRU_STORAGE_PATH`	`~/.paebiru`	Persistência (identidade, ledger, backlog)
`PAEBIRU_API_PORT`	`1975`	Porta da API HTTP/observabilidade
`PAEBIRU_SKIP_PF`	`false`	NUNCA `true` em produção (desabilita portão XDP)
`PAEBIRU_SKIP_TRACER`	`false`	NUNCA `true` em produção (desabilita OTel)
`PAEBIRU_SKIP_GEO_DISCOVERY`	`false`	Pula descoberta de geolocalização (use em CI)
`PAEBIRU_SKIP_GPU_TESTS`	`false`	Pula testes com CUDA (use em CI)
`RUST_LOG`	`info`	Verbosity: `trace` · `debug` · `info` · `warn` · `error`

Subir um nó local

cargo run -p paebiru-node

Saída esperada (em ~5 s):

NODE  Iniciando PAEBIRU Node (Trilha de Aço)...
NODE  Ponta-a-ponta rodando. Aguardando descoberta de peers...

Em outro terminal:

make test-local     # ciclo de vida ponta-a-ponta
# ou
curl http://localhost:1975/healthz

Para parar: Ctrl-C. O nó faz shutdown gracioso, fechando receipts em aberto e liberando peers.

Próximos passos

🌱 Primeiros passos — primeiro plasmídeo.
🔧 Caderno do operador — se você vai operar.
🛠️ Processo RSE — se você vai contribuir.

Solução de problemas

Sintoma	Causa provável	Solução
`error: linking with 'cc' failed` em macOS	Xcode CLT ausente	`xcode-select --install`
`couldn't find libbpf`	libbpf não instalado	`apt install libbpf-dev` ou `brew install libbpf`
`toolchain 'nightly-...' is not installed`	rustup não tem nightly	`rustup toolchain install nightly`
`permission denied` em `/var/run/tpm0`	TPM não presente	esperado em dev; em produção use nó com TPM 2.0
Porta 1975 ocupada	Outra instância rodando	`lsof -i :1975` ou mude `PAEBIRU_API_PORT`
mdBook não renderiza Mermaid	`mdbook-mermaid` ausente	`cargo install mdbook-mermaid`

Se persistir, abra issue no GitHub com a saída completa de nix develop --command bash -c 'make pre-commit 2>&1'.

Keyboard shortcuts

PAEBIRU