Zum Inhalt springen

Entwicklung ​

Bauen und ausführen ​

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

Weil 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.

bash
./scripts/check-deps.sh

Es 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 ​

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

Das 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, die Info.plist der Erweiterung (die Inhaltstypen, die sie vorsieht) und ihre Sandbox-Entitlements.
bash
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 ​

bash
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:

VariableBedeutung
NOTARY_KEYPfad zu einem App Store Connect API Key (.p8)
NOTARY_KEY_IDDie Key ID dieses Schlüssels
NOTARY_ISSUERDie Issuer-UUID, zu der der Schlüssel gehört
eine Developer ID Application-IdentitätWird automatisch erkannt, wenn genau eine im Schlüsselbund liegt, sonst MACOS_SIGN_IDENTITY setzen

Das Skript führt diese Schritte aus:

  1. Baut das Bundle, mit der aus dem Argument gestempelten Version.
  2. Baut die Quick-Look-Erweiterung mit build-quicklook.sh, signiert mit der Developer ID und den eigenen Sandbox-Entitlements der Erweiterung – nie scripts/entitlements.plist, denn eine App-Erweiterung muss sandboxed sein und die App nicht.
  3. Signiert von innen nach außen und ohne --deep zuerst das innere Executable und dann die App mit --options runtime --timestamp und scripts/entitlements.plist und prüft das Ergebnis mit codesign --verify --deep --strict.
  4. Baut ein UDZO-dmg mit einem Symlink auf /Applications.
  5. Signiert das dmg selbst.
  6. Reicht es mit notarytool submit --wait --timeout 300m ein.
  7. Heftet das Ticket an.
  8. Endet mit stapler validate und zwei spctl --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 .app trä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 ​

WorkflowAuslöserWas er tut
ci.ymlPush auf main, jeder Pull RequestAuf 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.ymlTag passend zu v*, oder manueller Start mit einer VersionDrei 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.ymlPush auf main, der das Redirect-Skript oder den Workflow berührt, oder manueller StartVerö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 ​

PlattformPaketHinweise
macOS 12+, Apple silicon.dmg, signiert und notarisiert, mit der Quick-Look-ErweiterungIn CI getestet, Quick-Look-Crate eingeschlossen
Linux x86_64.tar.gz des BinariesAuf 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.exeIn 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:

AdresseWasQuelle
ducklocal.appDie Produktseitehome/, statisches HTML und CSS
ducklocal.app/docsDiese Anleitungen, Englisch und Chinesischdocs/, 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:

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

Die 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 ​

PfadInhalt
src/main.rsEinstiegspunkt, frühe CLI-Verteilung, Einrichtung des GUI-Fensters
src/cli.rsHeadless-Argumente, Validierung durch den DuckDB-Parser, isolierte Verbindungen, JSON-Fehler und ihre Hinweise
tests/cli.rsIntegrationstests 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.rsAuflösen von Pfaden in anzuhängende Dateien und zu öffnende Datenbanken
src/db.rsDie DuckDB-Verbindung, Anhängen von Dateien, Server-Info
src/query.rsAbfrageausführung, Serialisierung der Ergebnisse, Export, EXPLAIN und das EXPLAIN-ANALYZE-Profil hinter Profile
src/script.rsAufteilen des Editor-Texts in die Anweisungen, die Run ausführt, Dot-Commands eingeschlossen
src/overview.rsDer Tab Übersicht der Ergebnisse: Statistiken und Verteilungen pro Spalte
src/extensions.rsDer Tab Erweiterungen der Seitenleiste: Auflisten, INSTALL, LOAD und UPDATE EXTENSIONS
src/storage.rsLesen des Headers einer .duckdb-Datei: warum eine Datei nicht öffnet, und welches DuckDB eine öffnende liest
src/schema_cli.rsducklocal schema: die abzufragenden Relationen und Spalten, zugeschnitten auf einen Prompt
src/profile.rsSpaltenstatistiken hinter ducklocal schema --stats
src/remote.rsducklocal open: der Loopback-Kanal zum laufenden Fenster, in beide Richtungen
src/schema.rsKatalog-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.rsExcel- und ODS-Arbeitsmappen, als eine Tabelle pro Blatt geladen
src/setup.rsBefehlszeile & KI…: ducklocal in den PATH legen und den Agent-Skill installieren
src/recents.rsDie zuletzt geöffneten Dashboards, die die Seitenleiste auflistet
src/history.rsDie eigene Datenbank der App: Verlauf, registrierte Dateien, angehängte Datenbanken, Einstellungen
src/s3.rsSigV4-Signierung und Auflistung in S3
src/i18n.rsDie String-Tabelle und die Sprachauswahl
src/state.rsAnwendungszustand, 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.rsStart 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.rsIcons, die über die Standardwerte der Komponentenbibliothek hinaus eingebettet sind
src/perf_probe.rsNur 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.

Veröffentlicht unter der Apache-2.0-Lizenz.