Ir para o conteúdo

Desenvolvimento ​

Compile e execute ​

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ávelSignificado
NOTARY_KEYCaminho para uma chave da API do App Store Connect (.p8)
NOTARY_KEY_IDO Key ID dessa chave
NOTARY_ISSUERO UUID do emissor ao qual a chave pertence
uma identidade Developer ID ApplicationDetectada 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 trabalhoGatilhoO que faz
ci.ymlPush para main, qualquer pull requestEm 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.ymlTag que corresponde a v*, ou execução manual com uma versãoTrê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.ymlPush para main que toque no script de redirecionamento ou no fluxo de trabalho, ou execução manualPublica 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 ​

PlataformaPacoteNotas
macOS 12+, Apple silicon.dmg, assinado e notarizado, com a extensão Quick LookTestado na CI, com o crate do Quick Look incluído
Linux x86_64.tar.gz do binárioCompilado 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.exeTestado 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çoO que éOrigem
ducklocal.appA página do produtohome/, HTML e CSS estáticos
ducklocal.app/docsEstes guias, em inglês e chinêsdocs/, 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:

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 ​

CaminhoConteúdo
src/main.rsPonto de entrada, despacho inicial da CLI, configuração da janela da GUI
src/cli.rsArgumentos sem interface, validação com o parser do DuckDB, conexões isoladas, erros JSON e seus hints
tests/cli.rsTestes 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.rsResolver caminhos em arquivos para anexar e bancos de dados para abrir
src/db.rsA conexão DuckDB, anexação de arquivos, informações do servidor
src/query.rsExecução de consultas, serialização de resultados, exportação, EXPLAIN e o perfil de EXPLAIN ANALYZE por trás do Perfil
src/script.rsDividir o texto do editor nas instruções que o Run executa, incluindo comandos com ponto
src/overview.rsA aba Visão geral dos resultados: estatísticas e distribuições por coluna
src/extensions.rsA aba Extensões da barra lateral: listar, INSTALL, LOAD e UPDATE EXTENSIONS
src/storage.rsLeitura do cabeçalho de um arquivo .duckdb: por que um arquivo não abre, e qual DuckDB lê um que abre
src/schema_cli.rsducklocal schema: as relações e colunas a consultar, dimensionadas para um prompt
src/profile.rsEstatísticas de colunas por trás de ducklocal schema --stats
src/remote.rsducklocal open: o canal de loopback para a janela em execução, nos dois sentidos
src/schema.rsIntrospecçã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.rsPastas de trabalho Excel e ODS, carregadas como uma tabela por planilha
src/setup.rsLinha de comando e IA…: colocar ducklocal no PATH e instalar a skill de agente
src/recents.rsOs painéis abertos recentemente que a barra lateral lista
src/history.rsO banco de dados do próprio app: histórico, arquivos registrados, bancos de dados anexados, configurações
src/s3.rsAssinatura SigV4 e listagem de S3
src/i18n.rsA tabela de strings e a seleção de idioma
src/state.rsEstado 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.rsInicializaçã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.rsArnê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.

Publicado sob a licença Apache-2.0.