Aller au contenu

Développement ​

Compiler et exécuter ​

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

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

bash
./scripts/check-deps.sh

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

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

Cela 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, le Info.plist de l'extension (les types de contenu qu'elle prévisualise) et ses droits de bac à sable.
bash
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 ​

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

VariableSignification
NOTARY_KEYChemin d'une clé d'API App Store Connect (.p8)
NOTARY_KEY_IDLe Key ID de cette clé
NOTARY_ISSUERL'UUID de l'émetteur auquel la clé appartient
une identité Developer ID ApplicationDétectée automatiquement quand une seule est dans le trousseau, sinon définissez MACOS_SIGN_IDENTITY

Le script effectue ces étapes :

  1. Compile le paquet, avec la version estampillée depuis l'argument.
  2. 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 — jamais scripts/entitlements.plist, car une extension d'application doit être isolée et l'application ne l'est pas.
  3. Signe, de l'intérieur vers l'extérieur et sans --deep, l'exécutable interne puis l'application avec --options runtime --timestamp et scripts/entitlements.plist, et vérifie le résultat avec codesign --verify --deep --strict.
  4. Construit un dmg UDZO avec un lien symbolique /Applications.
  5. Signe le dmg lui-même.
  6. Le soumet avec notarytool submit --wait --timeout 300m.
  7. Agrafe le ticket.
  8. Termine par stapler validate et deux contrôles spctl --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'.app interne 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 ​

FluxDéclencheurCe qu'il fait
ci.ymlEnvoi sur main, toute demande de tirageSur 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 versionTrois 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.ymlEnvoi sur main touchant le script de redirection ou le flux, ou déclenchement manuelPublie 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 ​

PlateformePaquetRemarques
macOS 12+, Apple silicon.dmg, signé et notarisé, avec l'extension Quick LookTesté en CI, crate Quick Look incluse
Linux x86_64.tar.gz du binaireCompilé 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.exeTesté 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 :

AdresseContenuSource
ducklocal.appLa page produithome/, HTML et CSS statiques
ducklocal.app/docsCes guides, en anglais et en chinoisdocs/, 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 :

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

L'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 ​

CheminContenu
src/main.rsPoint d'entrée, répartition précoce des commandes CLI, configuration de la fenêtre GUI
src/cli.rsArguments sans interface, validation par le parseur DuckDB, connexions isolées, erreurs JSON et leurs indices
tests/cli.rsTests 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.rsRésolution des chemins en fichiers à attacher et bases de données à ouvrir
src/db.rsLa connexion DuckDB, l'attachement des fichiers, les informations du serveur
src/query.rsExécution des requêtes, sérialisation des résultats, export, EXPLAIN et le profil EXPLAIN ANALYZE derrière Profile
src/script.rsDécoupage du texte de l'éditeur en instructions exécutées par Run, commandes point comprises
src/overview.rsL'onglet Overview des résultats : statistiques et distributions par colonne
src/extensions.rsL'onglet Extensions de la barre latérale : liste, INSTALL, LOAD et UPDATE EXTENSIONS
src/storage.rsLecture 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.rsducklocal schema : les relations et colonnes à interroger, dimensionnées pour un prompt
src/profile.rsStatistiques de colonnes derrière ducklocal schema --stats
src/remote.rsducklocal open : le canal local vers la fenêtre en cours, dans les deux sens
src/schema.rsIntrospection 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.rsClasseurs Excel et ODS, chargés en une table par feuille
src/setup.rsCommand line & AI… : placer ducklocal dans le PATH et installer la compétence d'agent
src/recents.rsLes tableaux de bord récemment ouverts que liste la barre latérale
src/history.rsLa base de données propre à l'application : historique, fichiers enregistrés, bases attachées, paramètres
src/s3.rsSignature SigV4 et listage S3
src/i18n.rsLa table de chaînes et le choix de la langue
src/state.rsL'é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.rsDé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.rsIcônes embarquées au-delà des valeurs par défaut de la bibliothèque de composants
src/perf_probe.rsHarnais 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.

Publié sous licence Apache-2.0.