Desenvolvimento
Compile e execute
cargo run # empty in-memory workspace
cargo run -- ./data/logs/ # open something straight away
cargo test --workspace # run the test suite, Quick Look engine includedComo 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.
./scripts/check-deps.shEle 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
./scripts/bundle.sh
# produces target/release/DuckLocal.appIsso 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, oInfo.plistda extensão (os tipos de conteúdo que ela pré-visualiza) e seus entitlements de sandbox.
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
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:
- Compila o bundle, com a versão marcada a partir do argumento.
- 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 — nuncascripts/entitlements.plist, porque uma extensão de app precisa estar em sandbox e o app não está. - Assina, de dentro para fora e sem
--deep, o executável interno e depois o app com--options runtime --timestampescripts/entitlements.plist, e verifica o resultado comcodesign --verify --deep --strict. - Compila um dmg UDZO com um link simbólico para
/Applications. - Assina o próprio dmg.
- Envia com
notarytool submit --wait --timeout 300m. - Grampeia o ticket.
- Termina com
stapler validatemais duas verificaçõesspctl --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
.appinterno 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, e é servido pelo Cloudflare Workers como assets estáticos:
| Endereço | O que é | Origem |
|---|---|---|
| ducklocal.app | A página do produto | home/, HTML e CSS estáticos |
| ducklocal.app/docs | Estes guias, em inglês e chinês | docs/, um site VitePress |
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:
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/siteO 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.
