# Sviluppo

> Compila DuckLocal dai sorgenti con Rust e DuckDB, esegui i test, crea il bundle dell'app macOS e prepara una release per macOS, Linux e Windows.

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

## Compila ed esegui {#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
```

Poiché DuckDB viene compilato direttamente dal codice sorgente incluso, la prima
compilazione richiede tempo e diversi gigabyte di spazio su disco. Le dipendenze nel
profilo dev vengono compilate con `opt-level = 3`, il che allunga quella prima
compilazione ma mantiene reattivo lo sviluppo iterativo: le compilazioni successive
ricostruiscono solo `ducklocal`.

**Build compatta.** `cargo build --profile compact --locked` scrive un binario più
piccolo in `target/compact/`. Il profilo `compact` eredita da `release` (LTO, simboli
rimossi, `panic = "abort"`) ma compila Rust per la dimensione (`opt-level = "s"`),
mentre `libduckdb-sys` mantiene `opt-level = 3`, così i cicli di scansione, filtro e
aggregazione di DuckDB restano veloci. Usala quando la dimensione del download o
del disco conta più della velocità dei frame e delle query — misurale entrambe
sulla macchina di destinazione. Il workflow di release e i pacchetti che pubblica
usano il normale profilo `release`.

**Toolchain.** Non esiste un `rust-toolchain.toml` né una chiave `rust-version`,
quindi il minimo effettivo è fissato dalle dipendenze: `1.85.1`, richiesto da
`duckdb`. La CI usa stable senza altro.

## Il toolkit fissato

Il toolkit dell'interfaccia, `gpui-kit`, proviene dal repository
`longbridge/gpui-kit`, fissato di proposito a una singola revisione git. Mescolare
due revisioni mette due copie di `gpui-base` nella build, e la build fallisce con
errori di trait non corrispondenti che non nominano la vera causa.

```bash
./scripts/check-deps.sh
```

Controlla le cose che Cargo non controlla: una sola revisione in tutte le
dipendenze dal repository, un `Cargo.lock` che concorda con essa, e nessun crate
due volte nella build — una dal repository e una da crates.io. Legge i due manifest
e nient'altro, quindi è offline e immediato. La CI lo esegue prima dei test. Per
passare a un toolkit più recente, cambia insieme tutti i `rev` in `Cargo.toml`,
esegui `cargo update` ed esegui lo script.

Il blocco a una revisione git è anche il motivo per cui il crate DuckLocal non è
pubblicabile su crates.io: una dipendenza git viene rifiutata lì.
La distribuzione avviene tramite i pacchetti di release qui sotto.

## Crea il bundle di un'app macOS

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

Questo assembla il bundle — binario in `Contents/MacOS/ducklocal`, più
`assets/Info.plist`, `assets/AppIcon.icns` e l'estensione Quick Look — ma **non lo
firma** per la distribuzione. Il risultato funziona sulla tua macchina e verrà
rifiutato da Gatekeeper ovunque altro.

### L'estensione Quick Look

L'anteprima con la barra spaziatrice nel Finder di file Parquet, DuckDB, CSV, TSV e
JSON Lines è un'estensione dell'app, `DuckLocalPreview.appex`, in `Contents/PlugIns`
dell'app. Ha due metà:

- `quicklook/` è un crate del workspace, `ducklocal-quicklook`: il motore di
  anteprima in Rust, compilato come libreria statica. Apre il file con lo stesso
  DuckDB incluso dell'app (dallo stesso lockfile, così DuckDB viene compilato una
  volta) e rende le sue colonne e le prime 50 righe come un'unica pagina HTML
  autocontenuta. Un'estensione è un processo in sandbox separato e non può chiamare
  l'app.
- `quicklook/extension/` è il guscio Swift intorno: `PreviewProvider.swift`,
  l'header C, l'`Info.plist` dell'estensione (i tipi di contenuto che visualizza in
  anteprima) e i suoi entitlement di sandbox.

```bash
scripts/build-quicklook.sh <DuckLocal.app> [signing identity]
```

Lo script compila il motore (`cargo build --release -p ducklocal-quicklook`, o per
`RUST_TARGET` quando è impostato, come fa il workflow di release, così la build di
DuckDB dell'app viene riusata), compila il guscio Swift rispetto a esso con
`swiftc` per macOS 12, copia l'`Info.plist` con la versione dell'app e firma
l'`.appex` con gli entitlement propri dell'estensione — ad hoc senza un'identità.
`bundle.sh` lo chiama senza identità. macOS trova l'estensione una volta che l'app
è stata avviata o registrata.

## Pacchettizza, firma e notarizza

```bash
scripts/package-macos.sh <binary> <output.dmg> <version>
```

Eseguilo dalla radice del repository; scrive `DuckLocal.app` e `dmg-root` nella
directory di lavoro e il dmg accanto a loro. Lo script si rifiuta di girare senza
credenziali — un artefatto non notarizzato non è qualcosa che un utente può aprire
su macOS attuale, quindi fallisce subito invece di produrne uno per caso.

Necessario:

| Variabile | Significato |
| --- | --- |
| `NOTARY_KEY` | Percorso di una chiave API di App Store Connect (`.p8`) |
| `NOTARY_KEY_ID` | Il Key ID di quella chiave |
| `NOTARY_ISSUER` | L'UUID dell'emittente a cui appartiene la chiave |
| un'identità Developer ID Application | Rilevata automaticamente quando ce n'è esattamente una nel portachiavi, altrimenti imposta `MACOS_SIGN_IDENTITY` |

Lo script esegue questi passaggi:

1. Crea il bundle, con la versione presa dall'argomento.
2. Compila l'estensione Quick Look con `build-quicklook.sh`, firmata con la
   Developer ID e gli entitlement di sandbox propri dell'estensione — mai
   `scripts/entitlements.plist`, perché un'estensione dell'app deve essere in
   sandbox e l'app non lo è.
3. Firma, dall'interno verso l'esterno e senza `--deep`, l'eseguibile interno e poi
   l'app con `--options runtime --timestamp` e `scripts/entitlements.plist`, e
   verifica il risultato con `codesign --verify --deep --strict`.
4. Crea un dmg UDZO con un symlink a `/Applications`.
5. **Firma il dmg stesso**.
6. Lo invia con `notarytool submit --wait --timeout 300m`.
7. Applica il ticket (staple).
8. Termina con `stapler validate` più due controlli `spctl --assess`.

Due cose da sapere prima di usarlo:

- Il timeout di cinque ore è un'attesa lato client, non una cancellazione. Se scade,
  l'invio continua l'elaborazione sul lato Apple e il ticket può essere ritirato più
  tardi — ma **un ticket è legato ai byte esatti inviati**, quindi non ricompilare;
  applica il ticket al file che hai inviato.
- Viene notarizzato solo il dmg, quindi l'`.app` interno non porta un ticket
  applicato. Un primo avvio da un'immagine appena montata richiede la rete per il
  check-in con Apple.

L'entitlement `com.apple.security.cs.disable-library-validation` è necessario,
perché DuckDB fa `dlopen` delle sue estensioni — `httpfs` tra queste.

## CI e release

| Workflow | Trigger | Cosa fa |
| --- | --- | --- |
| `ci.yml` | Push su `main`, qualsiasi pull request | Su `macos-latest`: `scripts/check-deps.sh`, `cargo fmt --all --check`, `cargo clippy --locked --workspace --all-targets -- -D warnings`, poi `cargo test --locked --workspace` (l'app e il crate Quick Look). Su `windows-latest`: `cargo test --locked` (i test `perf_probe` saltati), poi `scripts/check-windows.py` sull'eseguibile di debug. Su `ubuntu-22.04`: `cargo build --locked` |
| `release.yml` | Tag che corrisponde a `v*`, o dispatch manuale con una versione | Tre build: `aarch64-apple-darwin`, firmata e notarizzata con `package-macos.sh` in `ducklocal-macos-arm64.dmg`; Linux su Ubuntu 22.04 in `ducklocal-linux-x86_64.tar.gz`; Windows in `ducklocal-windows-x86_64.zip`, dopo che `scripts/check-windows.py` verifica l'eseguibile di release. Il job di release attende tutti e tre — uno che fallisce fa fallire la release — e crea la release GitHub con note generate |
| `gh-pages.yml` | Push su `main` che tocca lo script dei redirect o il workflow, o dispatch manuale | Pubblica su GitHub Pages i redirect dai vecchi indirizzi `jetsquirrel.github.io/DuckLocal/` al nuovo sito |

La build di release richiede questi secret del repository: `MACOS_CERTIFICATE`,
`MACOS_CERTIFICATE_PWD`, `NOTARY_KEY_BASE64`, `NOTARY_KEY_ID` e
`NOTARY_ISSUER`.

## Supporto delle piattaforme

| Piattaforma | Pacchetto | Note |
| --- | --- | --- |
| macOS 12+, Apple silicon | `.dmg`, firmato e notarizzato, con l'estensione Quick Look | Testato in CI, crate Quick Look incluso |
| Linux x86_64 | `.tar.gz` del binario | Compilato su Ubuntu 22.04, per una glibc abbastanza vecchia per la maggior parte delle distribuzioni, con le librerie di sistema che installa la CI di gpui-kit |
| Windows x86_64 | `.zip` di `ducklocal.exe` | Testato in CI. Non firmato: non c'è un certificato Windows, quindi SmartScreen avvisa al primo avvio |

I test girano su macOS e Windows; Linux viene compilato a ogni pull request ma non
testato. Windows li esegue perché i suoi percorsi — lettere di unità, `\`, nessun
`$HOME` — sono dove un'esecuzione su macOS non può intercettare un errore.
`scripts/check-windows.py` (Python della libreria standard, eseguito su Windows)
controlla poi l'eseguibile senza avviare la GUI: il sottosistema GUI, così non si
apre una finestra della console; l'icona dell'anatra incorporata; e che `--version`
e un `query` scrivano nell'output reindirizzato. Non esiste una build per Mac Intel.

Le scorciatoie sono legate con il modificatore `secondary` di gpui — ⌘ su macOS,
Ctrl su Windows e Linux. `cmd` sarebbe il tasto Windows su Windows e Linux, il che
rende ogni scorciatoia irraggiungibile.

## Il sito della documentazione

Il sito web vive in un repository separato,
[JetSquirrel/ducklocal-site](https://github.com/JetSquirrel/ducklocal-site), ed è
servito da Cloudflare Workers come asset statici:

| Indirizzo | Cosa | Origine |
| --- | --- | --- |
| [ducklocal.app](https://ducklocal.app/) | La pagina del prodotto | `home/`, HTML e CSS statici |
| [ducklocal.app/docs](https://ducklocal.app/docs/) | Queste guide, in inglese e cinese | `docs/`, un sito [VitePress](https://vitepress.dev/) |

Una modifica all'app che cambia ciò che dicono le guide richiede una pull request in
entrambi i repository. Per lavorare alle guide in locale, i prerequisiti sono
Node.js 22 o più recente (consigliato 24 LTS) e un clone del repository del sito.
Poi esegui:

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

La vecchia pagina GitHub Pages, `jetsquirrel.github.io/DuckLocal/`, è mantenuta come
un insieme di redirect alle pagine nuove corrispondenti; il `gh-pages.yml` di questo
repository li pubblica.

## Struttura del progetto

| Percorso | Contenuto |
| --- | --- |
| `src/main.rs` | Punto di ingresso, dispatch iniziale della CLI, configurazione della finestra GUI |
| `src/cli.rs` | Argomenti headless, validazione del parser DuckDB, connessioni isolate, errori JSON e i loro hint |
| `tests/cli.rs` | Test di integrazione con l'eseguibile reale; dati temporanei sotto `target/cli-tests` |
| `skills/ducklocal/` | Skill ufficiale per agenti SQL orientata prima allo schema, e riferimento della CLI |
| `src/sources.rs` | Risoluzione dei percorsi in file da collegare e database da aprire |
| `src/db.rs` | La connessione DuckDB, il collegamento dei file, le informazioni del server |
| `src/query.rs` | Esecuzione delle query, serializzazione dei risultati, esportazione, EXPLAIN e il profilo EXPLAIN ANALYZE dietro **Profilo** |
| `src/script.rs` | Divisione del testo dell'editor nelle istruzioni che esegue Run, comandi con punto inclusi |
| `src/overview.rs` | La scheda **Panoramica** dei risultati: statistiche e distribuzioni per colonna |
| `src/extensions.rs` | La scheda **Estensioni** della barra laterale: elenco, `INSTALL`, `LOAD` e `UPDATE EXTENSIONS` |
| `src/storage.rs` | Lettura dell'header di un file `.duckdb`: perché un file non si apre, e quale DuckDB ne legge uno che si apre |
| `src/schema_cli.rs` | `ducklocal schema`: le relazioni e le colonne da interrogare, dimensionate per un prompt |
| `src/profile.rs` | Statistiche delle colonne dietro `ducklocal schema --stats` |
| `src/remote.rs` | `ducklocal open`: il canale di loopback verso la finestra in esecuzione, in entrambe le direzioni |
| `src/schema.rs` | Introspezione del catalogo per la barra laterale |
| `src/spec/` | Dashboard `.dash`: il parser, la validazione, le origini, i filtri, i commenti di revisione (`ducklocal comments`), `ducklocal lsp` e la scheda della dashboard con i suoi grafici |
| `src/excel.rs` | Cartelle di lavoro Excel e ODS, caricate come una tabella per foglio |
| `src/setup.rs` | **Riga di comando e IA…**: mettere `ducklocal` nel PATH e installare la skill per agenti |
| `src/recents.rs` | Le dashboard aperte di recente che elenca la barra laterale |
| `src/history.rs` | Il database proprio dell'app: cronologia, file registrati, database collegati, impostazioni |
| `src/s3.rs` | Firma SigV4 e listing S3 |
| `src/i18n.rs` | La tabella delle stringhe e la selezione della lingua |
| `src/state.rs` | Stato dell'applicazione condiviso tra le viste |
| `src/ui/` | Editor, griglia dei risultati, grafici e mappe (con le tessere OpenStreetMap), barra laterale, dialoghi, barre del titolo e di stato, il controllo degli aggiornamenti |
| `src/windows.rs` | Avvio su Windows: la console del chiamante per i comandi CLI, nessuna per un avvio della GUI |
| `quicklook/` | L'anteprima Quick Look di macOS: una libreria Rust a cui si collega un'estensione Swift, compilata da `scripts/build-quicklook.sh` |
| `src/assets.rs` | Icone incorporate oltre i valori predefiniti della libreria di componenti |
| `src/perf_probe.rs` | Harness di sonda delle prestazioni solo per i test: tempo reale, numero di allocazioni e byte per i percorsi che scalano con la dimensione dei dati |
| `assets/` | Icone (`.icns`, `.ico` di Windows e script delle risorse), `Info.plist` con i tipi di documento che il Finder apre in DuckLocal, il diagramma usato dal README e dalla documentazione |
| `scripts/` | `bundle.sh`, `build-quicklook.sh`, `package-macos.sh`, `check-deps.sh`, `check-windows.py`, `make-icons.py`, entitlement |

## Note sui test

La suite di test è `cargo test --workspace`; un semplice `cargo test` copre l'app ma
non il crate `quicklook/`. I test di esecuzione delle query esercitano DuckDB
tramite una connessione in memoria; i test di esportazione coprono CSV e Parquet,
quest'ultimo rileggendo il file scritto con `read_parquet`.
