Développement
Compiler et exécuter
cargo run # empty in-memory workspace
cargo run -- ./data/logs/ # open something straight away
cargo test --workspace # run the test suite, Quick Look engine includedComme DuckDB est compilé directement depuis du code source embarqué, la première compilation prend un temps notable et exige plusieurs gigaoctets d'espace disque. Les dépendances du profil de développement sont compilées avec opt-level = 3, ce qui allonge cette première compilation mais garde le développement itératif réactif : les compilations suivantes ne recompilent que ducklocal.
Compilation compacte. cargo build --profile compact --locked écrit un binaire plus petit dans target/compact/. Le profil compact hérite de release (LTO, symboles supprimés, panic = "abort") mais compile le Rust pour la taille (opt-level = "s"), tandis que libduckdb-sys conserve opt-level = 3, pour que les boucles de parcours, de filtre et d'agrégation de DuckDB restent rapides. Utilisez-le quand la taille du téléchargement ou du disque compte plus que la vitesse d'affichage et d'exécution des requêtes — mesurez les deux sur la machine cible. Le flux de publication et les paquets qu'il publie utilisent le profil release normal.
Chaîne d'outils. Il n'y a ni rust-toolchain.toml ni clé rust-version : le plancher effectif est donc fixé par les dépendances : 1.85.1, exigé par duckdb. La CI utilise la version stable simple.
La boîte à outils épinglée
La boîte à outils d'interface, gpui-kit, vient du dépôt longbridge/gpui-kit, épinglé à une seule révision git à dessein. Mélanger deux révisions place deux copies de gpui-base dans la compilation, et la compilation échoue avec des erreurs de traits incompatibles qui ne nomment pas la vraie cause.
./scripts/check-deps.shIl vérifie ce que Cargo ne vérifie pas : une seule révision pour toutes les dépendances du dépôt, un Cargo.lock qui la respecte, et aucune crate présente deux fois dans la compilation — une fois depuis le dépôt, une fois depuis crates.io. Il ne lit que les deux manifestes, rien d'autre : il est donc hors ligne et immédiat. La CI l'exécute avant les tests. Pour passer à une boîte à outils plus récente, modifiez toutes les valeurs rev du Cargo.toml ensemble, lancez cargo update, puis le script.
L'épinglage à une révision git explique aussi pourquoi la crate DuckLocal n'est pas publiable sur crates.io : une dépendance git y est refusée. La distribution passe par les paquets de publication ci-dessous.
Empaqueter une application macOS
./scripts/bundle.sh
# produces target/release/DuckLocal.appCela assemble le paquet — binaire dans Contents/MacOS/ducklocal, plus assets/Info.plist, assets/AppIcon.icns et l'extension Quick Look — mais ne le signe pas pour la distribution. Le résultat fonctionne sur votre machine et sera refusé par Gatekeeper partout ailleurs.
L'extension Quick Look
L'aperçu par barre d'espace des fichiers Parquet, DuckDB, CSV, TSV et JSON Lines dans le Finder est une extension d'application, DuckLocalPreview.appex, dans le dossier Contents/PlugIns de l'application. Elle a deux moitiés :
quicklook/est une crate d'espace de travail,ducklocal-quicklook: le moteur d'aperçu en Rust, compilé en bibliothèque statique. Il ouvre le fichier avec le même DuckDB embarqué que l'application (depuis le même fichier de verrouillage, si bien que DuckDB ne compile qu'une fois) et rend ses colonnes et ses 50 premières lignes en une seule page HTML autonome. Une extension est son propre processus isolé et ne peut pas appeler l'application.quicklook/extension/est l'enveloppe Swift autour d'elle :PreviewProvider.swift, l'en-tête C, leInfo.plistde l'extension (les types de contenu qu'elle prévisualise) et ses droits de bac à sable.
scripts/build-quicklook.sh <DuckLocal.app> [signing identity]Le script compile le moteur (cargo build --release -p ducklocal-quicklook, ou pour RUST_TARGET quand il est défini, comme le fait le flux de publication, afin que la compilation de DuckDB de l'application soit réutilisée), compile l'enveloppe Swift contre lui avec swiftc pour macOS 12, copie le Info.plist estampillé de la version de l'application, et signe l'.appex avec les droits propres à l'extension — ad hoc sans identité. bundle.sh l'appelle sans identité. macOS trouve l'extension une fois l'application lancée ou enregistrée.
Empaqueter, signer et notariser
scripts/package-macos.sh <binary> <output.dmg> <version>Lancez-le depuis la racine du dépôt ; il écrit DuckLocal.app et dmg-root dans le répertoire de travail et le dmg à côté. Le script refuse de s'exécuter sans identifiants — un artefact non notarisé n'est pas quelque chose qu'un utilisateur peut ouvrir sur les versions actuelles de macOS, il échoue donc vite plutôt que d'en produire un par accident.
Requis :
| Variable | Signification |
|---|---|
NOTARY_KEY | Chemin d'une clé d'API App Store Connect (.p8) |
NOTARY_KEY_ID | Le Key ID de cette clé |
NOTARY_ISSUER | L'UUID de l'émetteur auquel la clé appartient |
| une identité Developer ID Application | Détectée automatiquement quand une seule est dans le trousseau, sinon définissez MACOS_SIGN_IDENTITY |
Le script effectue ces étapes :
- Compile le paquet, avec la version estampillée depuis l'argument.
- Compile l'extension Quick Look avec
build-quicklook.sh, signée avec l'identité Developer ID et les droits de bac à sable propres à l'extension — jamaisscripts/entitlements.plist, car une extension d'application doit être isolée et l'application ne l'est pas. - Signe, de l'intérieur vers l'extérieur et sans
--deep, l'exécutable interne puis l'application avec--options runtime --timestampetscripts/entitlements.plist, et vérifie le résultat aveccodesign --verify --deep --strict. - Construit un dmg UDZO avec un lien symbolique
/Applications. - Signe le dmg lui-même.
- Le soumet avec
notarytool submit --wait --timeout 300m. - Agrafe le ticket.
- Termine par
stapler validateet deux contrôlesspctl --assess.
Deux choses à savoir avant de l'utiliser :
- Le délai de cinq heures est une attente côté client, pas une annulation. S'il expire, la soumission continue d'être traitée chez Apple, et le ticket peut être récupéré plus tard — mais un ticket est lié aux octets exacts soumis : ne recompilez donc pas ; agrafez le fichier que vous avez soumis.
- Seul le dmg est notarisé, l'
.appinterne ne porte donc aucun ticket agrafé. Un premier lancement depuis une image tout juste montée exige un réseau pour se présenter à Apple.
Le droit com.apple.security.cs.disable-library-validation est nécessaire, parce que DuckDB fait un dlopen de ses extensions — httpfs entre autres.
CI et versions
| Flux | Déclencheur | Ce qu'il fait |
|---|---|---|
ci.yml | Envoi sur main, toute demande de tirage | Sur macos-latest : scripts/check-deps.sh, cargo fmt --all --check, cargo clippy --locked --workspace --all-targets -- -D warnings, puis cargo test --locked --workspace (l'application et la crate Quick Look). Sur windows-latest : cargo test --locked (les tests perf_probe ignorés), puis scripts/check-windows.py sur l'exécutable de débogage. Sur ubuntu-22.04 : cargo build --locked |
release.yml | Étiquette correspondant à v*, ou déclenchement manuel avec une version | Trois compilations : aarch64-apple-darwin, signée et notarisée avec package-macos.sh en ducklocal-macos-arm64.dmg ; Linux sur Ubuntu 22.04 en ducklocal-linux-x86_64.tar.gz ; Windows en ducklocal-windows-x86_64.zip, après que scripts/check-windows.py a vérifié l'exécutable de publication. La tâche de publication attend les trois — un échec fait échouer la version — et crée la version GitHub avec des notes générées |
gh-pages.yml | Envoi sur main touchant le script de redirection ou le flux, ou déclenchement manuel | Publie des redirections depuis les anciennes adresses jetsquirrel.github.io/DuckLocal/ vers le nouveau site sur GitHub Pages |
La compilation de publication a besoin de ces secrets du dépôt : MACOS_CERTIFICATE, MACOS_CERTIFICATE_PWD, NOTARY_KEY_BASE64, NOTARY_KEY_ID et NOTARY_ISSUER.
Prise en charge des plateformes
| Plateforme | Paquet | Remarques |
|---|---|---|
| macOS 12+, Apple silicon | .dmg, signé et notarisé, avec l'extension Quick Look | Testé en CI, crate Quick Look incluse |
| Linux x86_64 | .tar.gz du binaire | Compilé sur Ubuntu 22.04, pour une glibc assez ancienne pour la plupart des distributions, avec les bibliothèques système que la CI de gpui-kit installe |
| Windows x86_64 | .zip de ducklocal.exe | Testé en CI. Non signé : il n'y a pas de certificat Windows, SmartScreen avertit donc au premier lancement |
Les tests s'exécutent sur macOS et Windows ; Linux est compilé à chaque demande de tirage mais n'est pas testé. Windows les exécute parce que ses chemins — lettres de lecteur, \, absence de $HOME — sont là où une exécution macOS ne peut pas repérer une erreur. scripts/check-windows.py (Python de bibliothèque standard, exécuté sous Windows) vérifie ensuite l'exécutable sans lancer l'interface graphique : le sous-système GUI, pour qu'aucune fenêtre de console ne s'ouvre ; l'icône de canard embarquée ; et que --version et une query écrivent dans une sortie redirigée. Il n'y a pas de compilation pour Mac Intel.
Les raccourcis sont liés avec le modificateur secondary de gpui — ⌘ sous macOS, Ctrl sous Windows et Linux. cmd serait la touche Windows sous Windows et Linux, ce qui rendrait chaque raccourci inaccessible.
Le site de documentation
Le site web vit dans son propre dépôt, JetSquirrel/ducklocal-site, et est servi par Cloudflare Workers en tant qu'actifs statiques :
| Adresse | Contenu | Source |
|---|---|---|
| ducklocal.app | La page produit | home/, HTML et CSS statiques |
| ducklocal.app/docs | Ces guides, en anglais et en chinois | docs/, un site VitePress |
Une modification de l'application qui change ce que disent les guides exige une demande de tirage sur les deux dépôts. Pour travailler sur les guides en local, les prérequis sont Node.js 22 ou plus récent (24 LTS recommandé) et un clone du dépôt du site. Lancez ensuite :
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/siteL'ancienne adresse GitHub Pages, jetsquirrel.github.io/DuckLocal/, est conservée sous forme d'un ensemble de redirections vers les nouvelles pages correspondantes ; le gh-pages.yml de ce dépôt les publie.
Organisation du projet
| Chemin | Contenu |
|---|---|
src/main.rs | Point d'entrée, répartition précoce des commandes CLI, configuration de la fenêtre GUI |
src/cli.rs | Arguments sans interface, validation par le parseur DuckDB, connexions isolées, erreurs JSON et leurs indices |
tests/cli.rs | Tests d'intégration sur l'exécutable réel ; données temporaires sous target/cli-tests |
skills/ducklocal/ | Compétence d'agent SQL officielle, schéma d'abord, et référence de la CLI |
src/sources.rs | Résolution des chemins en fichiers à attacher et bases de données à ouvrir |
src/db.rs | La connexion DuckDB, l'attachement des fichiers, les informations du serveur |
src/query.rs | Exécution des requêtes, sérialisation des résultats, export, EXPLAIN et le profil EXPLAIN ANALYZE derrière Profile |
src/script.rs | Découpage du texte de l'éditeur en instructions exécutées par Run, commandes point comprises |
src/overview.rs | L'onglet Overview des résultats : statistiques et distributions par colonne |
src/extensions.rs | L'onglet Extensions de la barre latérale : liste, INSTALL, LOAD et UPDATE EXTENSIONS |
src/storage.rs | Lecture de l'en-tête d'un fichier .duckdb : pourquoi un fichier ne s'ouvre pas, et quel DuckDB en lit un qui s'ouvre |
src/schema_cli.rs | ducklocal schema : les relations et colonnes à interroger, dimensionnées pour un prompt |
src/profile.rs | Statistiques de colonnes derrière ducklocal schema --stats |
src/remote.rs | ducklocal open : le canal local vers la fenêtre en cours, dans les deux sens |
src/schema.rs | Introspection du catalogue pour la barre latérale |
src/spec/ | Tableaux de bord .dash : le parseur, la validation, les sources, les filtres, les commentaires de relecture (ducklocal comments), ducklocal lsp, et l'onglet du tableau de bord avec ses graphiques |
src/excel.rs | Classeurs Excel et ODS, chargés en une table par feuille |
src/setup.rs | Command line & AI… : placer ducklocal dans le PATH et installer la compétence d'agent |
src/recents.rs | Les tableaux de bord récemment ouverts que liste la barre latérale |
src/history.rs | La base de données propre à l'application : historique, fichiers enregistrés, bases attachées, paramètres |
src/s3.rs | Signature SigV4 et listage S3 |
src/i18n.rs | La table de chaînes et le choix de la langue |
src/state.rs | L'état de l'application partagé entre les vues |
src/ui/ | Éditeur, grille de résultats, graphiques et cartes (avec les tuiles OpenStreetMap), barre latérale, boîtes de dialogue, barres de titre et d'état, vérification des mises à jour |
src/windows.rs | Démarrage sous Windows : la console de l'appelant pour les commandes CLI, aucune pour un lancement GUI |
quicklook/ | L'aperçu Quick Look de macOS : une bibliothèque Rust liée par une extension Swift, compilée par scripts/build-quicklook.sh |
src/assets.rs | Icônes embarquées au-delà des valeurs par défaut de la bibliothèque de composants |
src/perf_probe.rs | Harnais de sonde de performance réservé aux tests : temps réel, nombre d'allocations et octets pour les chemins dont le coût croît avec la taille des données |
assets/ | Icônes (.icns, .ico Windows et script de ressources), Info.plist avec les types de documents que le Finder ouvre dans DuckLocal, le diagramme utilisé par le README et la doc |
scripts/ | bundle.sh, build-quicklook.sh, package-macos.sh, check-deps.sh, check-windows.py, make-icons.py, les droits (entitlements) |
Notes sur les tests
La suite de tests est cargo test --workspace ; un simple cargo test couvre l'application mais pas la crate quicklook/. Les tests d'exécution de requêtes exercent DuckDB via une connexion en mémoire ; les tests d'export couvrent le CSV et le Parquet, ce dernier en relisant le fichier écrit avec read_parquet.
