Sviluppo
Compila ed esegui
cargo run # empty in-memory workspace
cargo run -- ./data/logs/ # open something straight away
cargo test --workspace # run the test suite, Quick Look engine includedPoiché DuckDB viene compilato direttamente dal codice sorgente incluso, la prima compilazione richiede tempo e diversi gigabyte di spazio su disco. Le dipendenze nel profilo dev vengono compilate con opt-level = 3, il che allunga quella prima compilazione ma mantiene reattivo lo sviluppo iterativo: le compilazioni successive ricostruiscono solo ducklocal.
Build compatta. cargo build --profile compact --locked scrive un binario più piccolo in target/compact/. Il profilo compact eredita da release (LTO, simboli rimossi, panic = "abort") ma compila Rust per la dimensione (opt-level = "s"), mentre libduckdb-sys mantiene opt-level = 3, così i cicli di scansione, filtro e aggregazione di DuckDB restano veloci. Usala quando la dimensione del download o del disco conta più della velocità dei frame e delle query — misurale entrambe sulla macchina di destinazione. Il workflow di release e i pacchetti che pubblica usano il normale profilo release.
Toolchain. Non esiste un rust-toolchain.toml né una chiave rust-version, quindi il minimo effettivo è fissato dalle dipendenze: 1.85.1, richiesto da duckdb. La CI usa stable senza altro.
Il toolkit fissato
Il toolkit dell'interfaccia, gpui-kit, proviene dal repository longbridge/gpui-kit, fissato di proposito a una singola revisione git. Mescolare due revisioni mette due copie di gpui-base nella build, e la build fallisce con errori di trait non corrispondenti che non nominano la vera causa.
./scripts/check-deps.shControlla le cose che Cargo non controlla: una sola revisione in tutte le dipendenze dal repository, un Cargo.lock che concorda con essa, e nessun crate due volte nella build — una dal repository e una da crates.io. Legge i due manifest e nient'altro, quindi è offline e immediato. La CI lo esegue prima dei test. Per passare a un toolkit più recente, cambia insieme tutti i rev in Cargo.toml, esegui cargo update ed esegui lo script.
Il blocco a una revisione git è anche il motivo per cui il crate DuckLocal non è pubblicabile su crates.io: una dipendenza git viene rifiutata lì. La distribuzione avviene tramite i pacchetti di release qui sotto.
Crea il bundle di un'app macOS
./scripts/bundle.sh
# produces target/release/DuckLocal.appQuesto assembla il bundle — binario in Contents/MacOS/ducklocal, più assets/Info.plist, assets/AppIcon.icns e l'estensione Quick Look — ma non lo firma per la distribuzione. Il risultato funziona sulla tua macchina e verrà rifiutato da Gatekeeper ovunque altro.
L'estensione Quick Look
L'anteprima con la barra spaziatrice nel Finder di file Parquet, DuckDB, CSV, TSV e JSON Lines è un'estensione dell'app, DuckLocalPreview.appex, in Contents/PlugIns dell'app. Ha due metà:
quicklook/è un crate del workspace,ducklocal-quicklook: il motore di anteprima in Rust, compilato come libreria statica. Apre il file con lo stesso DuckDB incluso dell'app (dallo stesso lockfile, così DuckDB viene compilato una volta) e rende le sue colonne e le prime 50 righe come un'unica pagina HTML autocontenuta. Un'estensione è un processo in sandbox separato e non può chiamare l'app.quicklook/extension/è il guscio Swift intorno:PreviewProvider.swift, l'header C, l'Info.plistdell'estensione (i tipi di contenuto che visualizza in anteprima) e i suoi entitlement di sandbox.
scripts/build-quicklook.sh <DuckLocal.app> [signing identity]Lo script compila il motore (cargo build --release -p ducklocal-quicklook, o per RUST_TARGET quando è impostato, come fa il workflow di release, così la build di DuckDB dell'app viene riusata), compila il guscio Swift rispetto a esso con swiftc per macOS 12, copia l'Info.plist con la versione dell'app e firma l'.appex con gli entitlement propri dell'estensione — ad hoc senza un'identità. bundle.sh lo chiama senza identità. macOS trova l'estensione una volta che l'app è stata avviata o registrata.
Pacchettizza, firma e notarizza
scripts/package-macos.sh <binary> <output.dmg> <version>Eseguilo dalla radice del repository; scrive DuckLocal.app e dmg-root nella directory di lavoro e il dmg accanto a loro. Lo script si rifiuta di girare senza credenziali — un artefatto non notarizzato non è qualcosa che un utente può aprire su macOS attuale, quindi fallisce subito invece di produrne uno per caso.
Necessario:
| Variabile | Significato |
|---|---|
NOTARY_KEY | Percorso di una chiave API di App Store Connect (.p8) |
NOTARY_KEY_ID | Il Key ID di quella chiave |
NOTARY_ISSUER | L'UUID dell'emittente a cui appartiene la chiave |
| un'identità Developer ID Application | Rilevata automaticamente quando ce n'è esattamente una nel portachiavi, altrimenti imposta MACOS_SIGN_IDENTITY |
Lo script esegue questi passaggi:
- Crea il bundle, con la versione presa dall'argomento.
- Compila l'estensione Quick Look con
build-quicklook.sh, firmata con la Developer ID e gli entitlement di sandbox propri dell'estensione — maiscripts/entitlements.plist, perché un'estensione dell'app deve essere in sandbox e l'app non lo è. - Firma, dall'interno verso l'esterno e senza
--deep, l'eseguibile interno e poi l'app con--options runtime --timestampescripts/entitlements.plist, e verifica il risultato concodesign --verify --deep --strict. - Crea un dmg UDZO con un symlink a
/Applications. - Firma il dmg stesso.
- Lo invia con
notarytool submit --wait --timeout 300m. - Applica il ticket (staple).
- Termina con
stapler validatepiù due controllispctl --assess.
Due cose da sapere prima di usarlo:
- Il timeout di cinque ore è un'attesa lato client, non una cancellazione. Se scade, l'invio continua l'elaborazione sul lato Apple e il ticket può essere ritirato più tardi — ma un ticket è legato ai byte esatti inviati, quindi non ricompilare; applica il ticket al file che hai inviato.
- Viene notarizzato solo il dmg, quindi l'
.appinterno non porta un ticket applicato. Un primo avvio da un'immagine appena montata richiede la rete per il check-in con Apple.
L'entitlement com.apple.security.cs.disable-library-validation è necessario, perché DuckDB fa dlopen delle sue estensioni — httpfs tra queste.
CI e release
| Workflow | Trigger | Cosa fa |
|---|---|---|
ci.yml | Push su main, qualsiasi pull request | Su macos-latest: scripts/check-deps.sh, cargo fmt --all --check, cargo clippy --locked --workspace --all-targets -- -D warnings, poi cargo test --locked --workspace (l'app e il crate Quick Look). Su windows-latest: cargo test --locked (i test perf_probe saltati), poi scripts/check-windows.py sull'eseguibile di debug. Su ubuntu-22.04: cargo build --locked |
release.yml | Tag che corrisponde a v*, o dispatch manuale con una versione | Tre build: aarch64-apple-darwin, firmata e notarizzata con package-macos.sh in ducklocal-macos-arm64.dmg; Linux su Ubuntu 22.04 in ducklocal-linux-x86_64.tar.gz; Windows in ducklocal-windows-x86_64.zip, dopo che scripts/check-windows.py verifica l'eseguibile di release. Il job di release attende tutti e tre — uno che fallisce fa fallire la release — e crea la release GitHub con note generate |
gh-pages.yml | Push su main che tocca lo script dei redirect o il workflow, o dispatch manuale | Pubblica su GitHub Pages i redirect dai vecchi indirizzi jetsquirrel.github.io/DuckLocal/ al nuovo sito |
La build di release richiede questi secret del repository: MACOS_CERTIFICATE, MACOS_CERTIFICATE_PWD, NOTARY_KEY_BASE64, NOTARY_KEY_ID e NOTARY_ISSUER.
Supporto delle piattaforme
| Piattaforma | Pacchetto | Note |
|---|---|---|
| macOS 12+, Apple silicon | .dmg, firmato e notarizzato, con l'estensione Quick Look | Testato in CI, crate Quick Look incluso |
| Linux x86_64 | .tar.gz del binario | Compilato su Ubuntu 22.04, per una glibc abbastanza vecchia per la maggior parte delle distribuzioni, con le librerie di sistema che installa la CI di gpui-kit |
| Windows x86_64 | .zip di ducklocal.exe | Testato in CI. Non firmato: non c'è un certificato Windows, quindi SmartScreen avvisa al primo avvio |
I test girano su macOS e Windows; Linux viene compilato a ogni pull request ma non testato. Windows li esegue perché i suoi percorsi — lettere di unità, \, nessun $HOME — sono dove un'esecuzione su macOS non può intercettare un errore. scripts/check-windows.py (Python della libreria standard, eseguito su Windows) controlla poi l'eseguibile senza avviare la GUI: il sottosistema GUI, così non si apre una finestra della console; l'icona dell'anatra incorporata; e che --version e un query scrivano nell'output reindirizzato. Non esiste una build per Mac Intel.
Le scorciatoie sono legate con il modificatore secondary di gpui — ⌘ su macOS, Ctrl su Windows e Linux. cmd sarebbe il tasto Windows su Windows e Linux, il che rende ogni scorciatoia irraggiungibile.
Il sito della documentazione
Il sito web vive in un repository separato, JetSquirrel/ducklocal-site, ed è servito da Cloudflare Workers come asset statici:
| Indirizzo | Cosa | Origine |
|---|---|---|
| ducklocal.app | La pagina del prodotto | home/, HTML e CSS statici |
| ducklocal.app/docs | Queste guide, in inglese e cinese | docs/, un sito VitePress |
Una modifica all'app che cambia ciò che dicono le guide richiede una pull request in entrambi i repository. Per lavorare alle guide in locale, i prerequisiti sono Node.js 22 o più recente (consigliato 24 LTS) e un clone del repository del sito. Poi esegui:
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/siteLa vecchia pagina GitHub Pages, jetsquirrel.github.io/DuckLocal/, è mantenuta come un insieme di redirect alle pagine nuove corrispondenti; il gh-pages.yml di questo repository li pubblica.
Struttura del progetto
| Percorso | Contenuto |
|---|---|
src/main.rs | Punto di ingresso, dispatch iniziale della CLI, configurazione della finestra GUI |
src/cli.rs | Argomenti headless, validazione del parser DuckDB, connessioni isolate, errori JSON e i loro hint |
tests/cli.rs | Test di integrazione con l'eseguibile reale; dati temporanei sotto target/cli-tests |
skills/ducklocal/ | Skill ufficiale per agenti SQL orientata prima allo schema, e riferimento della CLI |
src/sources.rs | Risoluzione dei percorsi in file da collegare e database da aprire |
src/db.rs | La connessione DuckDB, il collegamento dei file, le informazioni del server |
src/query.rs | Esecuzione delle query, serializzazione dei risultati, esportazione, EXPLAIN e il profilo EXPLAIN ANALYZE dietro Profilo |
src/script.rs | Divisione del testo dell'editor nelle istruzioni che esegue Run, comandi con punto inclusi |
src/overview.rs | La scheda Panoramica dei risultati: statistiche e distribuzioni per colonna |
src/extensions.rs | La scheda Estensioni della barra laterale: elenco, INSTALL, LOAD e UPDATE EXTENSIONS |
src/storage.rs | Lettura dell'header di un file .duckdb: perché un file non si apre, e quale DuckDB ne legge uno che si apre |
src/schema_cli.rs | ducklocal schema: le relazioni e le colonne da interrogare, dimensionate per un prompt |
src/profile.rs | Statistiche delle colonne dietro ducklocal schema --stats |
src/remote.rs | ducklocal open: il canale di loopback verso la finestra in esecuzione, in entrambe le direzioni |
src/schema.rs | Introspezione del catalogo per la barra laterale |
src/spec/ | Dashboard .dash: il parser, la validazione, le origini, i filtri, i commenti di revisione (ducklocal comments), ducklocal lsp e la scheda della dashboard con i suoi grafici |
src/excel.rs | Cartelle di lavoro Excel e ODS, caricate come una tabella per foglio |
src/setup.rs | Riga di comando e IA…: mettere ducklocal nel PATH e installare la skill per agenti |
src/recents.rs | Le dashboard aperte di recente che elenca la barra laterale |
src/history.rs | Il database proprio dell'app: cronologia, file registrati, database collegati, impostazioni |
src/s3.rs | Firma SigV4 e listing S3 |
src/i18n.rs | La tabella delle stringhe e la selezione della lingua |
src/state.rs | Stato dell'applicazione condiviso tra le viste |
src/ui/ | Editor, griglia dei risultati, grafici e mappe (con le tessere OpenStreetMap), barra laterale, dialoghi, barre del titolo e di stato, il controllo degli aggiornamenti |
src/windows.rs | Avvio su Windows: la console del chiamante per i comandi CLI, nessuna per un avvio della GUI |
quicklook/ | L'anteprima Quick Look di macOS: una libreria Rust a cui si collega un'estensione Swift, compilata da scripts/build-quicklook.sh |
src/assets.rs | Icone incorporate oltre i valori predefiniti della libreria di componenti |
src/perf_probe.rs | Harness di sonda delle prestazioni solo per i test: tempo reale, numero di allocazioni e byte per i percorsi che scalano con la dimensione dei dati |
assets/ | Icone (.icns, .ico di Windows e script delle risorse), Info.plist con i tipi di documento che il Finder apre in DuckLocal, il diagramma usato dal README e dalla documentazione |
scripts/ | bundle.sh, build-quicklook.sh, package-macos.sh, check-deps.sh, check-windows.py, make-icons.py, entitlement |
Note sui test
La suite di test è cargo test --workspace; un semplice cargo test copre l'app ma non il crate quicklook/. I test di esecuzione delle query esercitano DuckDB tramite una connessione in memoria; i test di esportazione coprono CSV e Parquet, quest'ultimo rileggendo il file scritto con read_parquet.
