# Entwicklung

> DuckLocal mit Rust und DuckDB aus dem Quellcode bauen, die Tests ausführen, die macOS-App bündeln und ein Release für macOS, Linux und Windows erstellen.

Source: https://ducklocal.app/docs/de/development

## Bauen und ausführen {#build-and-run}

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

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

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 `dlopen`t – `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](https://github.com/JetSquirrel/ducklocal-site),
und wird von Cloudflare Workers als statische Assets ausgeliefert:

| Adresse | Was | Quelle |
| --- | --- | --- |
| [ducklocal.app](https://ducklocal.app/) | Die Produktseite | `home/`, statisches HTML und CSS |
| [ducklocal.app/docs](https://ducklocal.app/docs/) | Diese Anleitungen, Englisch und Chinesisch | `docs/`, eine [VitePress](https://vitepress.dev/)-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

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