Ir al contenido

Desarrollo ​

Compilar y ejecutar ​

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:

VariableSignificado
NOTARY_KEYRuta a una clave de la API de App Store Connect (.p8)
NOTARY_KEY_IDEl Key ID de esa clave
NOTARY_ISSUEREl UUID del emisor al que pertenece la clave
una identidad Developer ID ApplicationSe 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 trabajoDisparadorQué hace
ci.ymlPush a main, cualquier pull requestEn 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.ymlEtiqueta que coincide con v*, o ejecución manual con una versiónTres 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.ymlPush a main que toque el script de redirección o el flujo de trabajo, o ejecución manualPublica 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 ​

PlataformaPaqueteNotas
macOS 12+, Apple silicon.dmg, firmado y notarizado, con la extensión Quick LookProbado en CI, crate de Quick Look incluido
Linux x86_64.tar.gz del binarioCompilado 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.exeProbado 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ónQuéOrigen
ducklocal.appLa página del productohome/, HTML y CSS estáticos
ducklocal.app/docsEstas guías, en inglés y chinodocs/, 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:

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 ​

RutaContenido
src/main.rsPunto de entrada, distribución temprana de la CLI, configuración de la ventana de la GUI
src/cli.rsArgumentos sin interfaz, validación del analizador de DuckDB, conexiones aisladas, errores JSON y sus pistas
tests/cli.rsPruebas 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.rsResolver rutas en archivos que adjuntar y bases de datos que abrir
src/db.rsLa conexión de DuckDB, la adjunción de archivos, la información del servidor
src/query.rsEjecución de consultas, serialización de resultados, exportación, EXPLAIN y el perfil de EXPLAIN ANALYZE detrás de Perfil
src/script.rsDividir el texto del editor en las sentencias que ejecuta Run, comandos con punto incluidos
src/overview.rsLa pestaña Resumen de los resultados: estadísticas y distribuciones por columna
src/extensions.rsLa pestaña Extensiones de la barra lateral: listar, INSTALL, LOAD y UPDATE EXTENSIONS
src/storage.rsLeer 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.rsducklocal schema: las relaciones y columnas que consultar, dimensionadas para un prompt
src/profile.rsEstadísticas de columna detrás de ducklocal schema --stats
src/remote.rsducklocal open: el canal de loopback a la ventana en ejecución, en ambos sentidos
src/schema.rsIntrospecció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.rsLibros de Excel y ODS, cargados como una tabla por hoja
src/setup.rsLínea de comandos e IA…: poner ducklocal en el PATH e instalar la habilidad de agente
src/recents.rsLos paneles abiertos recientemente que lista la barra lateral
src/history.rsLa base de datos propia de la app: historial, archivos registrados, bases de datos adjuntas, ajustes
src/s3.rsFirma SigV4 y listado de S3
src/i18n.rsLa tabla de cadenas y la selección de idioma
src/state.rsEstado 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.rsArranque 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.rsIconos incrustados más allá de los valores por defecto de la biblioteca de componentes
src/perf_probe.rsArné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.

Publicado bajo la licencia Apache-2.0.