# Desarrollo

> Compila DuckLocal desde el código fuente con Rust y DuckDB, ejecuta las pruebas, empaqueta la app de macOS y publica una versión para macOS, Linux y Windows.

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

## Compilar y ejecutar {#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
```

Como DuckDB se compila directamente desde el código fuente incluido, la primera compilación tarda bastante y necesita varios gigabytes de disco. Las dependencias del perfil de desarrollo se compilan con `opt-level = 3`, lo que alarga esa primera compilación pero mantiene ágil el desarrollo iterativo: las compilaciones posteriores solo reconstruyen `ducklocal`.

**Compilación compacta.** `cargo build --profile compact --locked` escribe un binario
más pequeño en `target/compact/`. El perfil `compact` hereda de `release` (LTO,
símbolos eliminados, `panic = "abort"`), pero compila Rust pensando en el tamaño
(`opt-level = "s"`), mientras que `libduckdb-sys` mantiene `opt-level = 3`, así que los
bucles de recorrido, filtrado y agregación de DuckDB siguen siendo rápidos. Úsalo cuando el tamaño de la descarga o del disco
importe más que la velocidad de fotogramas y de consulta; mide ambas cosas en la máquina de destino.
El flujo de trabajo de versión y los paquetes que publica usan el perfil normal `release`.

**Cadena de herramientas.** No hay `rust-toolchain.toml` ni clave `rust-version`, así que
el mínimo efectivo lo fijan las dependencias: `1.85.1`, exigido por `duckdb`.
La CI usa stable sin más.

## El kit de herramientas fijado

El kit de la interfaz, `gpui-kit`, viene del repositorio `longbridge/gpui-kit`,
fijado a propósito a una sola revisión de git. Mezclar dos revisiones mete dos
copias de `gpui-base` en la compilación, y la compilación falla con errores de
rasgos que no nombran la causa real.

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

Comprueba lo que Cargo no comprueba: una sola revisión en todas las dependencias del
repositorio, un `Cargo.lock` que concuerda con ella, y ningún crate dos veces en la compilación,
una desde el repositorio y otra desde crates.io. Solo lee los dos
manifiestos y nada más, así que es offline e inmediato. La CI lo ejecuta antes
de las pruebas. Para pasar a un kit más nuevo, cambia juntos todos los `rev` de
`Cargo.toml`, ejecuta `cargo update` y ejecuta el script.

Fijar a una revisión de git es también la razón de que el crate de DuckLocal no se pueda publicar
en crates.io: allí se rechaza una dependencia de git.
La distribución son los paquetes de versión de abajo.

## Empaquetar una app de macOS

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

Eso arma el bundle —el binario en `Contents/MacOS/ducklocal`, más
`assets/Info.plist`, `assets/AppIcon.icns` y la extensión Quick Look—, pero
**no lo firma** para distribuirlo. El resultado funciona en tu máquina y
Gatekeeper lo rechazará en cualquier otra.

### La extensión Quick Look

La vista previa con la barra espaciadora en Finder de archivos Parquet, DuckDB, CSV, TSV y JSON Lines
es una extensión de app, `DuckLocalPreview.appex`, dentro de
`Contents/PlugIns` de la app. Tiene dos mitades:

- `quicklook/` es un crate del workspace, `ducklocal-quicklook`: el motor de
  vista previa en Rust, compilado como biblioteca estática. Abre el archivo con el mismo
  DuckDB incluido que la app (del mismo lockfile, así que DuckDB se compila una vez)
  y representa sus columnas y las primeras 50 filas como una única página HTML
  autocontenida. Una extensión es su propio proceso en sandbox y no puede llamar a la app.
- `quicklook/extension/` es el envoltorio Swift que lo rodea: `PreviewProvider.swift`,
  la cabecera de C, el `Info.plist` de la extensión (los tipos de contenido que previsualiza)
  y sus entitlements de sandbox.

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

El script compila el motor (`cargo build --release -p ducklocal-quicklook`,
o para `RUST_TARGET` cuando está definido, como hace el flujo de versión, para que se reutilice
la compilación de DuckDB de la app), compila el envoltorio Swift contra él con `swiftc`
para macOS 12, copia el `Info.plist` marcado con la versión de la app y
firma el `.appex` con los entitlements propios de la extensión: ad hoc si no hay
identidad. `bundle.sh` lo llama sin identidad. macOS encuentra la extensión
una vez que la app se ha abierto o registrado.

## Empaquetar, firmar y notarizar

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

Ejecútalo desde la raíz del repositorio; escribe `DuckLocal.app` y `dmg-root` en
el directorio de trabajo y el dmg junto a ellos. El script se niega a ejecutarse
sin credenciales: un artefacto sin notarizar no es algo que un usuario pueda abrir
en macOS actual, así que falla rápido en lugar de producir uno por accidente.

Necesario:

| Variable | Significado |
| --- | --- |
| `NOTARY_KEY` | Ruta a una clave de la API de App Store Connect (`.p8`) |
| `NOTARY_KEY_ID` | El Key ID de esa clave |
| `NOTARY_ISSUER` | El UUID del emisor al que pertenece la clave |
| una identidad Developer ID Application | Se detecta automáticamente cuando hay exactamente una en el llavero; si no, define `MACOS_SIGN_IDENTITY` |

El script hace estos pasos:

1. Compila el bundle, con la versión marcada desde el argumento.
2. Compila la extensión Quick Look con `build-quicklook.sh`, firmada con la
   Developer ID y los entitlements de sandbox propios de la extensión; nunca
   `scripts/entitlements.plist`, porque una extensión de app debe estar en sandbox
   y la app no lo está.
3. Firma, de dentro hacia fuera y sin `--deep`, primero el ejecutable interno y luego la
   app con `--options runtime --timestamp` y `scripts/entitlements.plist`,
   y verifica el resultado con `codesign --verify --deep --strict`.
4. Compila un dmg UDZO con un enlace simbólico a `/Applications`.
5. **Firma el propio dmg**.
6. Lo envía con `notarytool submit --wait --timeout 300m`.
7. Engrapa el ticket.
8. Termina con `stapler validate` y dos comprobaciones `spctl --assess`.

Dos cosas que conviene saber antes de usarlo:

- El tiempo de espera de cinco horas es una espera en el cliente, no una cancelación. Si
  expira, el envío sigue procesándose en el lado de Apple y el ticket se puede
  recoger más tarde, pero **un ticket se vincula a los bytes exactos enviados**, así que
  no recompiles; engrapa el archivo que enviaste.
- Solo se notariza el dmg, así que el `.app` interno no lleva ticket engrapado. Un
  primer arranque desde una imagen recién montada necesita red para comunicarse con Apple.

El entitlement `com.apple.security.cs.disable-library-validation` es necesario,
porque DuckDB hace `dlopen` de sus extensiones, `httpfs` entre ellas.

## CI y versiones

| Flujo de trabajo | Disparador | Qué hace |
| --- | --- | --- |
| `ci.yml` | Push a `main`, cualquier pull request | En `macos-latest`: `scripts/check-deps.sh`, `cargo fmt --all --check`, `cargo clippy --locked --workspace --all-targets -- -D warnings`, y luego `cargo test --locked --workspace` (la app y el crate de Quick Look). En `windows-latest`: `cargo test --locked` (las pruebas de `perf_probe` omitidas), y luego `scripts/check-windows.py` sobre el ejecutable de depuración. En `ubuntu-22.04`: `cargo build --locked` |
| `release.yml` | Etiqueta que coincide con `v*`, o ejecución manual con una versión | Tres compilaciones: `aarch64-apple-darwin`, firmada y notarizada con `package-macos.sh` en `ducklocal-macos-arm64.dmg`; Linux en Ubuntu 22.04 en `ducklocal-linux-x86_64.tar.gz`; Windows en `ducklocal-windows-x86_64.zip`, después de que `scripts/check-windows.py` verifique el ejecutable de la versión. El trabajo de versión espera a las tres; si una falla, falla la versión, y crea la versión de GitHub con notas generadas |
| `gh-pages.yml` | Push a `main` que toque el script de redirección o el flujo de trabajo, o ejecución manual | Publica en GitHub Pages redirecciones de las antiguas direcciones `jetsquirrel.github.io/DuckLocal/` al sitio nuevo |

La compilación de versión necesita estos secretos del repositorio: `MACOS_CERTIFICATE`,
`MACOS_CERTIFICATE_PWD`, `NOTARY_KEY_BASE64`, `NOTARY_KEY_ID` y
`NOTARY_ISSUER`.

## Soporte de plataformas

| Plataforma | Paquete | Notas |
| --- | --- | --- |
| macOS 12+, Apple silicon | `.dmg`, firmado y notarizado, con la extensión Quick Look | Probado en CI, crate de Quick Look incluido |
| Linux x86_64 | `.tar.gz` del binario | Compilado en Ubuntu 22.04, para un glibc lo bastante antiguo para la mayoría de las distribuciones, con las bibliotecas del sistema que instala la propia CI de gpui-kit |
| Windows x86_64 | `.zip` de `ducklocal.exe` | Probado en CI. Sin firma de código: no hay certificado de Windows, así que SmartScreen avisa en el primer arranque |

Las pruebas se ejecutan en macOS y Windows; Linux se compila en cada pull request
pero no se prueba. Windows las ejecuta porque sus rutas —letras de unidad, `\`, sin
`$HOME`— son donde una ejecución en macOS no puede atrapar un error.
`scripts/check-windows.py` (Python de biblioteca estándar, ejecutado en Windows)
comprueba luego el ejecutable sin lanzar la GUI: el subsistema de GUI, para que no se
abra una ventana de consola; el icono de pato incrustado; y que `--version` y un
`query` impriman en la salida redirigida. No hay compilación para Mac Intel.

Los atajos se enlazan con el modificador `secondary` de gpui: ⌘ en macOS, Ctrl en
Windows y Linux. `cmd` sería la tecla Windows en Windows y Linux, lo que
deja todos los atajos inalcanzables.

## El sitio de documentación

El sitio web vive en su propio repositorio,
[JetSquirrel/ducklocal-site](https://github.com/JetSquirrel/ducklocal-site),
y lo sirve Cloudflare Workers como recursos estáticos:

| Dirección | Qué | Origen |
| --- | --- | --- |
| [ducklocal.app](https://ducklocal.app/) | La página del producto | `home/`, HTML y CSS estáticos |
| [ducklocal.app/docs](https://ducklocal.app/docs/) | Estas guías, en inglés y chino | `docs/`, un sitio [VitePress](https://vitepress.dev/) |

Un cambio en la app que cambie lo que dicen las guías necesita un pull request en
los dos repositorios. Para trabajar en las guías en local, los requisitos son
Node.js 22 o superior (se recomienda 24 LTS) y un clon del repositorio del sitio.
Luego ejecuta:

```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 antigua dirección de GitHub Pages, `jetsquirrel.github.io/DuckLocal/`, se mantiene como un
conjunto de redirecciones a las nuevas páginas correspondientes; el `gh-pages.yml` de este
repositorio las publica.

## Estructura del proyecto

| Ruta | Contenido |
| --- | --- |
| `src/main.rs` | Punto de entrada, distribución temprana de la CLI, configuración de la ventana de la GUI |
| `src/cli.rs` | Argumentos sin interfaz, validación del analizador de DuckDB, conexiones aisladas, errores JSON y sus pistas |
| `tests/cli.rs` | Pruebas de integración con el ejecutable real; datos temporales en `target/cli-tests` |
| `skills/ducklocal/` | Habilidad oficial de agente SQL que empieza por el esquema, y referencia de la CLI |
| `src/sources.rs` | Resolver rutas en archivos que adjuntar y bases de datos que abrir |
| `src/db.rs` | La conexión de DuckDB, la adjunción de archivos, la información del servidor |
| `src/query.rs` | Ejecución de consultas, serialización de resultados, exportación, EXPLAIN y el perfil de EXPLAIN ANALYZE detrás de **Perfil** |
| `src/script.rs` | Dividir el texto del editor en las sentencias que ejecuta Run, comandos con punto incluidos |
| `src/overview.rs` | La pestaña **Resumen** de los resultados: estadísticas y distribuciones por columna |
| `src/extensions.rs` | La pestaña **Extensiones** de la barra lateral: listar, `INSTALL`, `LOAD` y `UPDATE EXTENSIONS` |
| `src/storage.rs` | Leer la cabecera de un archivo `.duckdb`: por qué un archivo no se abre, y qué DuckDB lee uno que sí se abre |
| `src/schema_cli.rs` | `ducklocal schema`: las relaciones y columnas que consultar, dimensionadas para un prompt |
| `src/profile.rs` | Estadísticas de columna detrás de `ducklocal schema --stats` |
| `src/remote.rs` | `ducklocal open`: el canal de loopback a la ventana en ejecución, en ambos sentidos |
| `src/schema.rs` | Introspección del catálogo para la barra lateral |
| `src/spec/` | Paneles `.dash`: el analizador, la validación, las fuentes, los filtros, los comentarios de revisión (`ducklocal comments`), `ducklocal lsp` y la pestaña del panel con sus gráficos |
| `src/excel.rs` | Libros de Excel y ODS, cargados como una tabla por hoja |
| `src/setup.rs` | **Línea de comandos e IA…**: poner `ducklocal` en el PATH e instalar la habilidad de agente |
| `src/recents.rs` | Los paneles abiertos recientemente que lista la barra lateral |
| `src/history.rs` | La base de datos propia de la app: historial, archivos registrados, bases de datos adjuntas, ajustes |
| `src/s3.rs` | Firma SigV4 y listado de S3 |
| `src/i18n.rs` | La tabla de cadenas y la selección de idioma |
| `src/state.rs` | Estado de la aplicación compartido entre vistas |
| `src/ui/` | Editor, cuadrícula de resultados, gráficos y mapas (con las teselas de OpenStreetMap), barra lateral, diálogos, barras de título y de estado, la comprobación de actualizaciones |
| `src/windows.rs` | Arranque en Windows: la consola del llamador para los comandos de la CLI, ninguna para un arranque de la GUI |
| `quicklook/` | La vista previa de macOS Quick Look: una biblioteca de Rust contra la que enlaza una extensión Swift, compilada por `scripts/build-quicklook.sh` |
| `src/assets.rs` | Iconos incrustados más allá de los valores por defecto de la biblioteca de componentes |
| `src/perf_probe.rs` | Arnés de sondeo de rendimiento solo para pruebas: tiempo real, número de asignaciones y bytes en rutas que escalan con el tamaño de los datos |
| `assets/` | Iconos (`.icns`, `.ico` de Windows y script de recursos), `Info.plist` con los tipos de documento que Finder abre en DuckLocal, el diagrama que usan el README y la documentación |
| `scripts/` | `bundle.sh`, `build-quicklook.sh`, `package-macos.sh`, `check-deps.sh`, `check-windows.py`, `make-icons.py`, entitlements |

## Notas sobre las pruebas

La suite de pruebas es `cargo test --workspace`; un simple `cargo test` cubre la app
pero no el crate `quicklook/`. Las pruebas de ejecución de consultas ejercitan DuckDB mediante
una conexión en memoria; las pruebas de exportación cubren CSV y Parquet, esta última
leyendo de vuelta el archivo escrito con `read_parquet`.
