Desarrollo
Compilar y ejecutar
cargo run # empty in-memory workspace
cargo run -- ./data/logs/ # open something straight away
cargo test --workspace # run the test suite, Quick Look engine includedComo 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.
./scripts/check-deps.shComprueba 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
./scripts/bundle.sh
# produces target/release/DuckLocal.appEso 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, elInfo.plistde la extensión (los tipos de contenido que previsualiza) y sus entitlements de sandbox.
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
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:
- Compila el bundle, con la versión marcada desde el argumento.
- 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; nuncascripts/entitlements.plist, porque una extensión de app debe estar en sandbox y la app no lo está. - Firma, de dentro hacia fuera y sin
--deep, primero el ejecutable interno y luego la app con--options runtime --timestampyscripts/entitlements.plist, y verifica el resultado concodesign --verify --deep --strict. - Compila un dmg UDZO con un enlace simbólico a
/Applications. - Firma el propio dmg.
- Lo envía con
notarytool submit --wait --timeout 300m. - Engrapa el ticket.
- Termina con
stapler validatey dos comprobacionesspctl --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
.appinterno 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, y lo sirve Cloudflare Workers como recursos estáticos:
| Dirección | Qué | Origen |
|---|---|---|
| ducklocal.app | La página del producto | home/, HTML y CSS estáticos |
| ducklocal.app/docs | Estas guías, en inglés y chino | docs/, un sitio VitePress |
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:
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/siteLa 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.
