Entwicklung
Bauen und ausführen
cargo run # empty in-memory workspace
cargo run -- ./data/logs/ # open something straight away
cargo test --workspace # run the test suite, Quick Look engine includedWeil DuckDB direkt aus mitgeliefertem Quellcode kompiliert wird, dauert der erste Build spürbar lange und braucht mehrere Gigabyte Speicherplatz. Abhängigkeiten im dev-Profil werden mit opt-level = 3 kompiliert, was diesen ersten Build verlängert, die iterative Entwicklung aber reaktionsschnell hält – spätere Kompilierungen bauen nur ducklocal neu.
Kompakter Build. cargo build --profile compact --locked schreibt ein kleineres Binary nach target/compact/. Das Profil compact erbt von release (LTO, entfernte Symbole, panic = "abort"), kompiliert Rust aber auf Größe (opt-level = "s"), während libduckdb-sys bei opt-level = 3 bleibt, damit DuckDBs Scan-, Filter- und Aggregationsschleifen schnell bleiben. Nutzen Sie es, wenn Download- oder Datenträgergröße wichtiger sind als Bildrate und Abfragetempo – messen Sie beides auf der Zielmaschine. Der Release-Workflow und die von ihm veröffentlichten Pakete verwenden das normale Profil release.
Toolchain. Es gibt keine rust-toolchain.toml und keinen rust-version-Schlüssel, die effektive Untergrenze setzen also die Abhängigkeiten: 1.85.1, gefordert von duckdb. CI verwendet einfaches stable.
Das festgelegte Toolkit
Das UI-Toolkit gpui-kit stammt aus dem Repository longbridge/gpui-kit und ist absichtlich auf eine einzige git-Revision festgelegt. Zwei Revisionen zu mischen bringt zwei Kopien von gpui-base in den Build, und der Build scheitert mit Trait-Mismatch-Fehlern, die die eigentliche Ursache nicht nennen.
./scripts/check-deps.shEs prüft, was Cargo nicht prüft: eine Revision über alle Abhängigkeiten des Repositories hinweg, eine dazu passende Cargo.lock und kein Crate doppelt im Build – einmal aus dem Repository und einmal von crates.io. Es liest die beiden Manifeste und sonst nichts, ist also offline und sofort fertig. CI führt es vor den Tests aus. Um auf ein neueres Toolkit zu wechseln, ändern Sie alle rev in Cargo.toml gemeinsam, führen cargo update aus und lassen das Skript laufen.
Das Festlegen auf eine git-Revision ist auch der Grund, warum das Crate DuckLocal nicht auf crates.io veröffentlicht werden kann: Eine git-Abhängigkeit wird dort abgelehnt. Die Verteilung erfolgt über die Release-Pakete unten.
Eine macOS-App bündeln
./scripts/bundle.sh
# produces target/release/DuckLocal.appDas stellt das Bundle zusammen – Binary unter Contents/MacOS/ducklocal, dazu assets/Info.plist, assets/AppIcon.icns und die Quick-Look-Erweiterung –, signiert es aber nicht für die Verteilung. Das Ergebnis läuft auf Ihrem Rechner und wird überall sonst von Gatekeeper abgelehnt.
Die Quick-Look-Erweiterung
Die Vorschau von Parquet-, DuckDB-, CSV-, TSV- und JSON-Lines-Dateien per Leertaste im Finder ist eine App-Erweiterung, DuckLocalPreview.appex, im Ordner Contents/PlugIns der App. Sie hat zwei Hälften:
quicklook/ist ein Workspace-Crate,ducklocal-quicklook: die Vorschau-Engine in Rust, als statische Bibliothek gebaut. Sie öffnet die Datei mit demselben gebündelten DuckDB wie die App (aus demselben Lockfile, DuckDB wird also einmal kompiliert) und rendert ihre Spalten und die ersten 50 Zeilen als eine eigenständige HTML-Seite. Eine Erweiterung ist ein eigener, sandboxed Prozess und kann die App nicht aufrufen.quicklook/extension/ist die Swift-Hülle darum:PreviewProvider.swift, der C-Header, dieInfo.plistder Erweiterung (die Inhaltstypen, die sie vorsieht) und ihre Sandbox-Entitlements.
scripts/build-quicklook.sh <DuckLocal.app> [signing identity]Das Skript baut die Engine (cargo build --release -p ducklocal-quicklook, oder bei gesetztem RUST_TARGET für dieses Ziel, wie der Release-Workflow es tut, damit der DuckDB-Build der App wiederverwendet wird), kompiliert die Swift-Hülle mit swiftc für macOS 12 dagegen, kopiert die mit der Version der App gestempelte Info.plist und signiert die .appex mit den eigenen Entitlements der Erweiterung – ad hoc, wenn keine Identität vorliegt. bundle.sh ruft es ohne Identität auf. macOS findet die Erweiterung, sobald die App gestartet oder registriert wurde.
Packen, signieren und notarisieren
scripts/package-macos.sh <binary> <output.dmg> <version>Führen Sie es im Wurzelverzeichnis des Repositories aus; es schreibt DuckLocal.app und dmg-root in das Arbeitsverzeichnis und das dmg daneben. Das Skript verweigert den Lauf ohne Zugangsdaten – ein nicht notarisiertes Artefakt kann ein Benutzer unter aktuellem macOS nicht öffnen, es scheitert also lieber sofort, als versehentlich eines zu erzeugen.
Erforderlich:
| Variable | Bedeutung |
|---|---|
NOTARY_KEY | Pfad zu einem App Store Connect API Key (.p8) |
NOTARY_KEY_ID | Die Key ID dieses Schlüssels |
NOTARY_ISSUER | Die Issuer-UUID, zu der der Schlüssel gehört |
| eine Developer ID Application-Identität | Wird automatisch erkannt, wenn genau eine im Schlüsselbund liegt, sonst MACOS_SIGN_IDENTITY setzen |
Das Skript führt diese Schritte aus:
- Baut das Bundle, mit der aus dem Argument gestempelten Version.
- Baut die Quick-Look-Erweiterung mit
build-quicklook.sh, signiert mit der Developer ID und den eigenen Sandbox-Entitlements der Erweiterung – niescripts/entitlements.plist, denn eine App-Erweiterung muss sandboxed sein und die App nicht. - Signiert von innen nach außen und ohne
--deepzuerst das innere Executable und dann die App mit--options runtime --timestampundscripts/entitlements.plistund prüft das Ergebnis mitcodesign --verify --deep --strict. - Baut ein UDZO-dmg mit einem Symlink auf
/Applications. - Signiert das dmg selbst.
- Reicht es mit
notarytool submit --wait --timeout 300mein. - Heftet das Ticket an.
- Endet mit
stapler validateund zweispctl --assess-Prüfungen.
Zwei Dinge sollten Sie vor der Nutzung wissen:
- Die Frist von fünf Stunden ist ein clientseitiges Warten, keine Absage. Läuft sie ab, verarbeitet Apple die Einsendung weiter, und das Ticket kann später abgeholt werden – aber ein Ticket bindet an genau die eingereichten Bytes, bauen Sie also nicht neu; heften Sie das Ticket an die Datei, die Sie eingereicht haben.
- Nur das dmg wird notarisiert, das innere
.appträgt also kein angeheftetes Ticket. Ein erster Start aus einem gerade eingebundenen Image braucht Netzwerk, um sich bei Apple zu melden.
Das Entitlement com.apple.security.cs.disable-library-validation ist erforderlich, weil DuckDB seine Erweiterungen dlopent – httpfs darunter.
CI und Releases
| Workflow | Auslöser | Was er tut |
|---|---|---|
ci.yml | Push auf main, jeder Pull Request | Auf macos-latest: scripts/check-deps.sh, cargo fmt --all --check, cargo clippy --locked --workspace --all-targets -- -D warnings, dann cargo test --locked --workspace (die App und das Quick-Look-Crate). Auf windows-latest: cargo test --locked (die perf_probe-Tests übersprungen), dann scripts/check-windows.py auf dem Debug-Executable. Auf ubuntu-22.04: cargo build --locked |
release.yml | Tag passend zu v*, oder manueller Start mit einer Version | Drei Builds: aarch64-apple-darwin, signiert und notarisiert mit package-macos.sh zu ducklocal-macos-arm64.dmg; Linux auf Ubuntu 22.04 zu ducklocal-linux-x86_64.tar.gz; Windows zu ducklocal-windows-x86_64.zip, nachdem scripts/check-windows.py das Release-Executable geprüft hat. Der Release-Job wartet auf alle drei – ein Fehlschlag lässt das Release scheitern – und erstellt das GitHub-Release mit generierten Notes |
gh-pages.yml | Push auf main, der das Redirect-Skript oder den Workflow berührt, oder manueller Start | Veröffentlicht Weiterleitungen von den alten jetsquirrel.github.io/DuckLocal/-Adressen auf die neue Seite auf GitHub Pages |
Der Release-Build braucht diese Repository-Secrets: MACOS_CERTIFICATE, MACOS_CERTIFICATE_PWD, NOTARY_KEY_BASE64, NOTARY_KEY_ID und NOTARY_ISSUER.
Plattformunterstützung
| Plattform | Paket | Hinweise |
|---|---|---|
| macOS 12+, Apple silicon | .dmg, signiert und notarisiert, mit der Quick-Look-Erweiterung | In CI getestet, Quick-Look-Crate eingeschlossen |
| Linux x86_64 | .tar.gz des Binaries | Auf Ubuntu 22.04 gebaut, für ein glibc, das für die meisten Distributionen alt genug ist, mit den Systembibliotheken, die die CI von gpui-kit selbst installiert |
| Windows x86_64 | .zip von ducklocal.exe | In CI getestet. Nicht code-signiert: Es gibt kein Windows-Zertifikat, SmartScreen warnt beim ersten Start |
Die Tests laufen auf macOS und Windows; Linux wird bei jedem Pull Request kompiliert, aber nicht getestet. Windows führt sie aus, weil seine Pfade – Laufwerksbuchstaben, \, kein $HOME – dort liegen, wo ein Lauf unter macOS einen Fehler nicht fangen kann. scripts/check-windows.py (Python mit Standardbibliothek, unter Windows ausgeführt) prüft dann das Executable, ohne die GUI zu starten: das GUI-Subsystem, damit sich kein Konsolenfenster öffnet; das eingebettete Enten-Icon; und dass --version und ein query in umgeleitete Ausgabe schreiben. Es gibt keinen Build für Intel-Macs.
Tastenkürzel werden mit dem secondary-Modifier von gpui gebunden – ⌘ unter macOS, Ctrl unter Windows und Linux. cmd wäre unter Windows und Linux die Windows-Taste, was jedes Kürzel unerreichbar macht.
Die Dokumentationsseite
Die Website liegt in einem eigenen Repository, JetSquirrel/ducklocal-site, und wird von Cloudflare Workers als statische Assets ausgeliefert:
| Adresse | Was | Quelle |
|---|---|---|
| ducklocal.app | Die Produktseite | home/, statisches HTML und CSS |
| ducklocal.app/docs | Diese Anleitungen, Englisch und Chinesisch | docs/, eine VitePress-Seite |
Eine Änderung an der App, die ändert, was die Anleitungen sagen, braucht einen Pull Request in beiden Repositories. Um lokal an den Anleitungen zu arbeiten, sind Node.js 22 oder neuer (24 LTS empfohlen) und ein Klon des Site-Repositories die Voraussetzungen. Führen Sie dann aus:
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/siteDie alte GitHub-Pages-Adresse jetsquirrel.github.io/DuckLocal/ bleibt als Satz von Weiterleitungen auf die passenden neuen Seiten erhalten; gh-pages.yml in diesem Repository veröffentlicht sie.
Projektaufbau
| Pfad | Inhalt |
|---|---|
src/main.rs | Einstiegspunkt, frühe CLI-Verteilung, Einrichtung des GUI-Fensters |
src/cli.rs | Headless-Argumente, Validierung durch den DuckDB-Parser, isolierte Verbindungen, JSON-Fehler und ihre Hinweise |
tests/cli.rs | Integrationstests mit dem echten Executable; Scratch-Daten unter target/cli-tests |
skills/ducklocal/ | Offizieller schema-first Skill für SQL-Agenten und CLI-Referenz |
src/sources.rs | Auflösen von Pfaden in anzuhängende Dateien und zu öffnende Datenbanken |
src/db.rs | Die DuckDB-Verbindung, Anhängen von Dateien, Server-Info |
src/query.rs | Abfrageausführung, Serialisierung der Ergebnisse, Export, EXPLAIN und das EXPLAIN-ANALYZE-Profil hinter Profile |
src/script.rs | Aufteilen des Editor-Texts in die Anweisungen, die Run ausführt, Dot-Commands eingeschlossen |
src/overview.rs | Der Tab Übersicht der Ergebnisse: Statistiken und Verteilungen pro Spalte |
src/extensions.rs | Der Tab Erweiterungen der Seitenleiste: Auflisten, INSTALL, LOAD und UPDATE EXTENSIONS |
src/storage.rs | Lesen des Headers einer .duckdb-Datei: warum eine Datei nicht öffnet, und welches DuckDB eine öffnende liest |
src/schema_cli.rs | ducklocal schema: die abzufragenden Relationen und Spalten, zugeschnitten auf einen Prompt |
src/profile.rs | Spaltenstatistiken hinter ducklocal schema --stats |
src/remote.rs | ducklocal open: der Loopback-Kanal zum laufenden Fenster, in beide Richtungen |
src/schema.rs | Katalog-Introspektion für die Seitenleiste |
src/spec/ | .dash-Dashboards: der Parser, Validierung, Quellen, Filter, Review-Kommentare (ducklocal comments), ducklocal lsp und der Dashboard-Tab mit seinen Plots |
src/excel.rs | Excel- und ODS-Arbeitsmappen, als eine Tabelle pro Blatt geladen |
src/setup.rs | Befehlszeile & KI…: ducklocal in den PATH legen und den Agent-Skill installieren |
src/recents.rs | Die zuletzt geöffneten Dashboards, die die Seitenleiste auflistet |
src/history.rs | Die eigene Datenbank der App: Verlauf, registrierte Dateien, angehängte Datenbanken, Einstellungen |
src/s3.rs | SigV4-Signierung und Auflistung in S3 |
src/i18n.rs | Die String-Tabelle und die Sprachauswahl |
src/state.rs | Anwendungszustand, den alle Ansichten teilen |
src/ui/ | Editor, Ergebnisraster, Diagramme und Karten (mit den OpenStreetMap-Kacheln), Seitenleiste, Dialoge, Titel- und Statusleisten, die Update-Prüfung |
src/windows.rs | Start unter Windows: die Konsole des Aufrufers für CLI-Befehle, keine für einen GUI-Start |
quicklook/ | Die macOS-Vorschau für Quick Look: eine Rust-Bibliothek, gegen die eine Swift-Erweiterung linkt, gebaut von scripts/build-quicklook.sh |
src/assets.rs | Icons, die über die Standardwerte der Komponentenbibliothek hinaus eingebettet sind |
src/perf_probe.rs | Nur für Tests: Performance-Probe-Harness für Wandzeit, Allokationszahl und Bytes bei Pfaden, die mit der Datengröße skalieren |
assets/ | Icons (.icns, Windows .ico und Ressourcenskript), Info.plist mit den Dokumenttypen, die Finder in DuckLocal öffnet, das Diagramm, das README und Docs verwenden |
scripts/ | bundle.sh, build-quicklook.sh, package-macos.sh, check-deps.sh, check-windows.py, make-icons.py, Entitlements |
Hinweise zum Testen
Die Testsuite ist cargo test --workspace; einfaches cargo test deckt die App ab, aber nicht das Crate quicklook/. Tests zur Abfrageausführung üben DuckDB über eine In-Memory-Verbindung; die Export-Tests decken CSV und Parquet ab, Letzteres, indem die geschriebene Datei mit read_parquet wieder eingelesen wird.
