# Desenvolvimento

> Compile o DuckLocal a partir do código-fonte com Rust e DuckDB, execute os testes, empacote o app de macOS e publique uma release para macOS, Linux e Windows.

Source: https://ducklocal.app/docs/pt/development

## Compile e execute {#build-and-run}

```bash
cargo run                     # empty in-memory workspace
cargo run -- ./data/logs/     # open something straight away
cargo test --workspace        # run the test suite, Quick Look engine included
```

Como o DuckDB compila diretamente do código-fonte embutido, a compilação inicial
leva um tempo considerável e exige vários gigabytes de disco. As dependências no
perfil de desenvolvimento compilam com `opt-level = 3`, o que prolonga essa
primeira compilação mas mantém o desenvolvimento iterativo ágil — as compilações
seguintes só recompilam `ducklocal`.

**Compilação compacta.** `cargo build --profile compact --locked` grava um binário
menor em `target/compact/`. O perfil `compact` herda de `release` (LTO, símbolos
removidos, `panic = "abort"`), mas compila o Rust pensando no tamanho
(`opt-level = "s"`), enquanto `libduckdb-sys` mantém `opt-level = 3`, então os laços
de scan, filtro e agregação do DuckDB continuam rápidos. Use-o quando o tamanho do
download ou do disco importar mais que a velocidade de quadros e de consulta — meça
as duas na máquina de destino. O fluxo de trabalho de release e os pacotes que ele
publica usam o perfil `release` normal.

**Toolchain.** Não há `rust-toolchain.toml` nem chave `rust-version`, então o piso
efetivo é definido pelas dependências: `1.85.1`, exigido por `duckdb`. A CI usa o
stable comum.

## O kit de ferramentas fixado

O kit de interface, `gpui-kit`, vem do repositório `longbridge/gpui-kit`, fixado de
propósito em uma única revisão de git. Misturar duas revisões coloca duas cópias de
`gpui-base` na compilação, e a compilação falha com erros de trait que não nomeiam a
causa real.

```bash
./scripts/check-deps.sh
```

Ele verifica o que o Cargo não verifica: uma revisão única em todas as dependências
do repositório, um `Cargo.lock` que concorda com ela, e nenhum crate duplicado na
compilação — uma vez vindo do repositório e outra do crates.io. Ele lê os dois
manifestos e nada mais, então é off-line e imediato. A CI o executa antes dos
testes. Para passar a um kit mais novo, mude todos os `rev` no `Cargo.toml` juntos,
execute `cargo update` e execute o script.

Fixar em uma revisão de git é também o motivo de o crate do DuckLocal não ser
publicável no crates.io: uma dependência de git é recusada lá.
A distribuição são os pacotes de release abaixo.

## Empacote um app de macOS

```bash
./scripts/bundle.sh
# produces target/release/DuckLocal.app
```

Isso monta o bundle — binário em `Contents/MacOS/ducklocal`, mais
`assets/Info.plist`, `assets/AppIcon.icns` e a extensão Quick Look — mas **não o
assina** para distribuição. O resultado roda na sua máquina e será recusado pelo
Gatekeeper em qualquer outro lugar.

### A extensão Quick Look

A prévia de Parquet, DuckDB, CSV, TSV e arquivos JSON Lines ao pressionar a barra
de espaço no Finder é uma extensão de app, `DuckLocalPreview.appex`, em
`Contents/PlugIns` do app. Ela tem duas metades:

- `quicklook/` é um crate do workspace, `ducklocal-quicklook`: o motor de prévia em
  Rust, compilado como biblioteca estática. Ele abre o arquivo com o mesmo DuckDB
  embutido do app (do mesmo lockfile, então o DuckDB compila uma vez) e renderiza
  suas colunas e as primeiras 50 linhas como uma única página HTML autocontida. Uma
  extensão é um processo próprio em sandbox e não consegue chamar o app.
- `quicklook/extension/` é a camada Swift em volta dele: `PreviewProvider.swift`, o
  cabeçalho C, o `Info.plist` da extensão (os tipos de conteúdo que ela
  pré-visualiza) e seus entitlements de sandbox.

```bash
scripts/build-quicklook.sh <DuckLocal.app> [signing identity]
```

O script compila o motor (`cargo build --release -p ducklocal-quicklook`, ou para
`RUST_TARGET` quando definido, como o fluxo de release faz, para que a compilação
do DuckDB do app seja reaproveitada), compila a camada Swift contra ele com
`swiftc` para macOS 12, copia o `Info.plist` marcado com a versão do app, e assina
o `.appex` com os entitlements da própria extensão — ad hoc quando não há
identidade. O `bundle.sh` o chama sem identidade. O macOS encontra a extensão
depois que o app foi aberto ou registrado.

## Empacote, assine e notarize

```bash
scripts/package-macos.sh <binary> <output.dmg> <version>
```

Execute-o da raiz do repositório; ele escreve `DuckLocal.app` e `dmg-root` no
diretório de trabalho e o dmg ao lado deles. O script se recusa a rodar sem
credenciais — um artefato não notarizado não é algo que um usuário consiga abrir no
macOS atual, então ele falha rápido em vez de produzir um por acidente.

Necessário:

| Variável | Significado |
| --- | --- |
| `NOTARY_KEY` | Caminho para uma chave da API do App Store Connect (`.p8`) |
| `NOTARY_KEY_ID` | O Key ID dessa chave |
| `NOTARY_ISSUER` | O UUID do emissor ao qual a chave pertence |
| uma identidade Developer ID Application | Detectada automaticamente quando há exatamente uma no keychain; caso contrário, defina `MACOS_SIGN_IDENTITY` |

O script executa estes passos:

1. Compila o bundle, com a versão marcada a partir do argumento.
2. Compila a extensão Quick Look com `build-quicklook.sh`, assinada com a Developer
   ID e os entitlements de sandbox da própria extensão — nunca
   `scripts/entitlements.plist`, porque uma extensão de app precisa estar em
   sandbox e o app não está.
3. Assina, de dentro para fora e sem `--deep`, o executável interno e depois o app
   com `--options runtime --timestamp` e `scripts/entitlements.plist`, e verifica o
   resultado com `codesign --verify --deep --strict`.
4. Compila um dmg UDZO com um link simbólico para `/Applications`.
5. **Assina o próprio dmg**.
6. Envia com `notarytool submit --wait --timeout 300m`.
7. Grampeia o ticket.
8. Termina com `stapler validate` mais duas verificações `spctl --assess`.

Duas coisas para saber antes de usá-lo:

- O tempo limite de cinco horas é uma espera no cliente, não um cancelamento. Se
  ele expirar, o envio continua sendo processado do lado da Apple, e o ticket pode
  ser coletado depois — mas **um ticket se vincula aos bytes exatos enviados**, então
  não recompile; grampeie o arquivo que você enviou.
- Apenas o dmg é notarizado, então o `.app` interno não carrega um ticket
  grampeado. Uma primeira abertura a partir de uma imagem recém-montada precisa de
  rede para se comunicar com a Apple.

O entitlement `com.apple.security.cs.disable-library-validation` é necessário,
porque o DuckDB faz `dlopen` das suas extensões — `httpfs` entre elas.

## CI e releases

| Fluxo de trabalho | Gatilho | O que faz |
| --- | --- | --- |
| `ci.yml` | Push para `main`, qualquer pull request | Em `macos-latest`: `scripts/check-deps.sh`, `cargo fmt --all --check`, `cargo clippy --locked --workspace --all-targets -- -D warnings`, e depois `cargo test --locked --workspace` (o app e o crate do Quick Look). Em `windows-latest`: `cargo test --locked` (os testes de `perf_probe` ignorados), e depois `scripts/check-windows.py` no executável de depuração. Em `ubuntu-22.04`: `cargo build --locked` |
| `release.yml` | Tag que corresponde a `v*`, ou execução manual com uma versão | Três compilações: `aarch64-apple-darwin`, assinada e notarizada com `package-macos.sh` em `ducklocal-macos-arm64.dmg`; Linux no Ubuntu 22.04 em `ducklocal-linux-x86_64.tar.gz`; Windows em `ducklocal-windows-x86_64.zip`, depois que `scripts/check-windows.py` verifica o executável da release. O job de release espera os três — se um falhar, a release falha — e cria a release do GitHub com notas geradas |
| `gh-pages.yml` | Push para `main` que toque no script de redirecionamento ou no fluxo de trabalho, ou execução manual | Publica no GitHub Pages redirecionamentos dos endereços antigos `jetsquirrel.github.io/DuckLocal/` para o site novo |

A compilação de release precisa destes segredos do repositório: `MACOS_CERTIFICATE`,
`MACOS_CERTIFICATE_PWD`, `NOTARY_KEY_BASE64`, `NOTARY_KEY_ID` e `NOTARY_ISSUER`.

## Suporte a plataformas

| Plataforma | Pacote | Notas |
| --- | --- | --- |
| macOS 12+, Apple silicon | `.dmg`, assinado e notarizado, com a extensão Quick Look | Testado na CI, com o crate do Quick Look incluído |
| Linux x86_64 | `.tar.gz` do binário | Compilado no Ubuntu 22.04, para um glibc antigo o bastante para a maioria das distribuições, com as bibliotecas de sistema que a própria CI do gpui-kit instala |
| Windows x86_64 | `.zip` do `ducklocal.exe` | Testado na CI. Sem assinatura de código: não há certificado Windows, então o SmartScreen avisa na primeira abertura |

Os testes rodam no macOS e no Windows; o Linux é compilado em todo pull request mas
não é testado. O Windows os executa porque seus caminhos — letras de unidade, `\`,
sem `$HOME` — são onde uma execução no macOS não consegue pegar um erro.
`scripts/check-windows.py` (Python da biblioteca padrão, executado no Windows)
então verifica o executável sem iniciar a GUI: o subsistema de GUI, para que
nenhuma janela de console abra; o ícone do pato embutido; e que `--version` e um
`query` imprimam na saída redirecionada. Não há compilação para Mac Intel.

Os atalhos são vinculados com o modificador `secondary` do gpui — ⌘ no macOS, Ctrl
no Windows e no Linux. `cmd` seria a tecla Windows no Windows e no Linux, o que
deixaria todos os atalhos inalcançáveis.

## O site de documentação

O site fica em seu próprio repositório,
[JetSquirrel/ducklocal-site](https://github.com/JetSquirrel/ducklocal-site), e é
servido pelo Cloudflare Workers como assets estáticos:

| Endereço | O que é | Origem |
| --- | --- | --- |
| [ducklocal.app](https://ducklocal.app/) | A página do produto | `home/`, HTML e CSS estáticos |
| [ducklocal.app/docs](https://ducklocal.app/docs/) | Estes guias, em inglês e chinês | `docs/`, um site [VitePress](https://vitepress.dev/) |

Uma mudança no app que mude o que os guias dizem precisa de um pull request nos dois
repositórios. Para trabalhar nos guias localmente, os pré-requisitos são Node.js 22
ou mais recente (24 LTS recomendado) e um clone do repositório do site. Depois
execute:

```bash
npm --prefix docs ci             # install the locked dependencies
npm --prefix docs run dev        # http://localhost:5173/docs/
sh scripts/build.sh              # the whole site, product page and docs, in dist/site
```

O endereço antigo do GitHub Pages, `jetsquirrel.github.io/DuckLocal/`, é mantido como
um conjunto de redirecionamentos para as novas páginas correspondentes; o
`gh-pages.yml` deste repositório os publica.

## Estrutura do projeto

| Caminho | Conteúdo |
| --- | --- |
| `src/main.rs` | Ponto de entrada, despacho inicial da CLI, configuração da janela da GUI |
| `src/cli.rs` | Argumentos sem interface, validação com o parser do DuckDB, conexões isoladas, erros JSON e seus hints |
| `tests/cli.rs` | Testes de integração com o executável real; dados temporários em `target/cli-tests` |
| `skills/ducklocal/` | Skill oficial de agente SQL que começa pelo esquema, e referência da CLI |
| `src/sources.rs` | Resolver caminhos em arquivos para anexar e bancos de dados para abrir |
| `src/db.rs` | A conexão DuckDB, anexação de arquivos, informações do servidor |
| `src/query.rs` | Execução de consultas, serialização de resultados, exportação, EXPLAIN e o perfil de EXPLAIN ANALYZE por trás do **Perfil** |
| `src/script.rs` | Dividir o texto do editor nas instruções que o Run executa, incluindo comandos com ponto |
| `src/overview.rs` | A aba **Visão geral** dos resultados: estatísticas e distribuições por coluna |
| `src/extensions.rs` | A aba **Extensões** da barra lateral: listar, `INSTALL`, `LOAD` e `UPDATE EXTENSIONS` |
| `src/storage.rs` | Leitura do cabeçalho de um arquivo `.duckdb`: por que um arquivo não abre, e qual DuckDB lê um que abre |
| `src/schema_cli.rs` | `ducklocal schema`: as relações e colunas a consultar, dimensionadas para um prompt |
| `src/profile.rs` | Estatísticas de colunas por trás de `ducklocal schema --stats` |
| `src/remote.rs` | `ducklocal open`: o canal de loopback para a janela em execução, nos dois sentidos |
| `src/schema.rs` | Introspecção do catálogo para a barra lateral |
| `src/spec/` | Painéis `.dash`: o parser, a validação, as fontes, os filtros, os comentários de revisão (`ducklocal comments`), o `ducklocal lsp`, e a aba do painel com seus gráficos |
| `src/excel.rs` | Pastas de trabalho Excel e ODS, carregadas como uma tabela por planilha |
| `src/setup.rs` | **Linha de comando e IA…**: colocar `ducklocal` no PATH e instalar a skill de agente |
| `src/recents.rs` | Os painéis abertos recentemente que a barra lateral lista |
| `src/history.rs` | O banco de dados do próprio app: histórico, arquivos registrados, bancos de dados anexados, configurações |
| `src/s3.rs` | Assinatura SigV4 e listagem de S3 |
| `src/i18n.rs` | A tabela de strings e a seleção de idioma |
| `src/state.rs` | Estado da aplicação compartilhado entre as visões |
| `src/ui/` | Editor, grade de resultados, gráficos e mapas (com os tiles do OpenStreetMap), barra lateral, diálogos, barras de título e de status, a verificação de atualizações |
| `src/windows.rs` | Inicialização no Windows: o console de quem chamou para comandos da CLI, nenhum para uma abertura da GUI |
| `quicklook/` | A prévia do Quick Look do macOS: uma biblioteca Rust contra a qual uma extensão Swift se vincula, compilada por `scripts/build-quicklook.sh` |
| `src/assets.rs` | Ícones embutidos além dos padrões da biblioteca de componentes |
| `src/perf_probe.rs` | Arnês de sondagem de desempenho só para testes: tempo de relógio, número de alocações e bytes para caminhos que escalam com o tamanho dos dados |
| `assets/` | Ícones (`.icns`, `.ico` do Windows e script de recursos), `Info.plist` com os tipos de documento que o Finder abre no DuckLocal, o diagrama que o README e a documentação usam |
| `scripts/` | `bundle.sh`, `build-quicklook.sh`, `package-macos.sh`, `check-deps.sh`, `check-windows.py`, `make-icons.py`, entitlements |

## Notas sobre testes

A suíte de testes é `cargo test --workspace`; um `cargo test` simples cobre o app mas
não o crate `quicklook/`. Os testes de execução de consultas exercitam o DuckDB por
uma conexão em memória; os testes de exportação cobrem CSV e Parquet, este último
lendo de volta o arquivo gravado com `read_parquet`.
