# Développement

> Compilez DuckLocal depuis les sources avec Rust et DuckDB, exécutez les tests, empaquetez l'application macOS et publiez une version pour macOS, Linux et Windows.

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

## Compiler et exécuter {#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
```

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 :

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

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

| 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](https://github.com/JetSquirrel/ducklocal-site),
et est servi par Cloudflare Workers en tant qu'actifs statiques :

| Adresse | Contenu | Source |
| --- | --- | --- |
| [ducklocal.app](https://ducklocal.app/) | La page produit | `home/`, HTML et CSS statiques |
| [ducklocal.app/docs](https://ducklocal.app/docs/) | Ces guides, en anglais et en chinois | `docs/`, un site [VitePress](https://vitepress.dev/) |

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

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