Разработка
Сборка и запуск
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Поскольку DuckDB компилируется напрямую из вендорного исходного кода, первая сборка занимает заметное время и требует нескольких гигабайт на диске. Зависимости в профиле разработки компилируются с opt-level = 3, что удлиняет первую сборку, но сохраняет отзывчивость итеративной разработки — последующие компиляции пересобирают только ducklocal.
Компактная сборка. cargo build --profile compact --locked записывает меньший бинарный файл в target/compact/. Профиль compact наследует release (LTO, удалённые символы, panic = "abort"), но компилирует Rust с оглядкой на размер (opt-level = "s"), а libduckdb-sys сохраняет opt-level = 3, поэтому циклы сканирования, фильтрации и агрегации DuckDB остаются быстрыми. Используйте его, когда размер загрузки или диска важнее скорости отрисовки и запросов — измерьте и то и другое на целевой машине. Рабочий процесс выпуска и публикуемые им пакеты используют обычный профиль release.
Набор инструментов. Файла rust-toolchain.toml и ключа rust-version нет, поэтому фактический минимум задают зависимости: 1.85.1, требуется для duckdb. CI использует обычный stable.
Закреплённый набор инструментов
Набор инструментов интерфейса, gpui-kit, берётся из репозитория longbridge/gpui-kit, намеренно закреплённого на одной ревизии git. Смешивание двух ревизий помещает в сборку две копии gpui-base, и сборка падает с ошибками несовпадения трейтов, которые не называют настоящую причину.
./scripts/check-deps.shОн проверяет то, что Cargo не проверяет: одну ревизию во всех зависимостях от репозитория, Cargo.lock, который с ней согласуется, и отсутствие какого-либо крейта в сборке дважды — один раз из репозитория и один раз из crates.io. Он читает два манифеста и больше ничего, поэтому работает офлайн и сразу. CI запускает его перед тестами. Чтобы перейти на более новый набор инструментов, измените все rev в Cargo.toml вместе, выполните cargo update и запустите скрипт.
Закрепление на ревизии git — ещё и причина, по которой крейт DuckLocal нельзя опубликовать на crates.io: там git-зависимость отклоняется. Распространение идёт через пакеты выпуска, описанные ниже.
Упаковка приложения для macOS
./scripts/bundle.sh
# produces target/release/DuckLocal.appЭто собирает пакет приложения — бинарный файл в Contents/MacOS/ducklocal, а также assets/Info.plist, assets/AppIcon.icns и расширение Quick Look, — но не подписывает его для распространения. Результат работает на вашей машине, а Gatekeeper откажется запускать его где-либо ещё.
Расширение Quick Look
Предварительный просмотр файлов Parquet, DuckDB, CSV, TSV и JSON Lines по пробелу в Finder — это расширение приложения, DuckLocalPreview.appex, в Contents/PlugIns приложения. У него две половины:
quicklook/— это крейт рабочей области,ducklocal-quicklook: движок предварительного просмотра на Rust, собранный как статическая библиотека. Он открывает файл тем же встроенным DuckDB, что и приложение (из того же lock-файла, поэтому DuckDB компилируется один раз), и отображает его столбцы и первые 50 строк как одну самодостаточную HTML-страницу. Расширение — отдельный процесс в песочнице, и оно не может вызывать приложение.quicklook/extension/— оболочка на Swift вокруг него:PreviewProvider.swift, заголовок C,Info.plistрасширения (типы содержимого, которые оно показывает) и его entitlements для песочницы.
scripts/build-quicklook.sh <DuckLocal.app> [signing identity]Скрипт собирает движок (cargo build --release -p ducklocal-quicklook, а при заданном RUST_TARGET — для него, как делает рабочий процесс выпуска, чтобы сборка DuckDB приложения была переиспользована), компилирует против него оболочку Swift с помощью swiftc для macOS 12, копирует Info.plist со штампом версии приложения и подписывает .appex собственными entitlements расширения — ad hoc, без идентичности. bundle.sh вызывает его без идентичности. macOS находит расширение, когда приложение уже запускалось или было зарегистрировано.
Упаковка, подпись и нотаризация
scripts/package-macos.sh <binary> <output.dmg> <version>Запускайте его из корня репозитория; он записывает DuckLocal.app и dmg-root в рабочий каталог, а dmg — рядом с ними. Скрипт отказывается работать без учётных данных: артефакт без нотаризации пользователь не сможет открыть в актуальной macOS, поэтому скрипт быстро падает, а не создаёт его случайно.
Требуется:
| Переменная | Значение |
|---|---|
NOTARY_KEY | Путь к ключу API App Store Connect (.p8) |
NOTARY_KEY_ID | Key ID этого ключа |
NOTARY_ISSUER | UUID издателя, которому принадлежит ключ |
| идентичность Developer ID Application | Определяется автоматически, когда в связке ключей ровно одна; иначе задайте MACOS_SIGN_IDENTITY |
Скрипт выполняет такие шаги:
- Собирает пакет приложения со штампом версии из аргумента.
- Собирает расширение Quick Look через
build-quicklook.sh, подписанное Developer ID и собственными entitlements песочницы расширения — никогдаscripts/entitlements.plist, потому что расширение приложения должно быть в песочнице, а само приложение — нет. - Подписывает изнутри наружу и без
--deep: сначала внутренний исполняемый файл, затем приложение с--options runtime --timestampиscripts/entitlements.plist, и проверяет результат с помощьюcodesign --verify --deep --strict. - Собирает dmg UDZO с символической ссылкой на
/Applications. - Подписывает сам dmg.
- Отправляет его через
notarytool submit --wait --timeout 300m. - Прикрепляет тикет.
- Завершает
stapler validateи двумя проверкамиspctl --assess.
Две вещи, которые стоит знать перед использованием:
- Пятичасовой тайм-аут — это ожидание на стороне клиента, а не отмена. Если он истечёт, отправка продолжит обрабатываться на стороне Apple, и тикет можно получить позже, — но тикет привязан к точным отправленным байтам, поэтому не пересобирайте; прикрепляйте тикет к тому файлу, который отправили.
- Нотаризация выполняется только для dmg, поэтому внутренний
.appне несёт прикреплённого тикета. Первому запуску с только что смонтированного образа нужна сеть для связи с Apple.
Entitlement com.apple.security.cs.disable-library-validation необходим, потому что DuckDB делает dlopen своих расширений — в том числе httpfs.
CI и выпуски
| Рабочий процесс | Триггер | Что делает |
|---|---|---|
ci.yml | Push в main, любой pull request | На macos-latest: scripts/check-deps.sh, cargo fmt --all --check, cargo clippy --locked --workspace --all-targets -- -D warnings, затем cargo test --locked --workspace (приложение и крейт Quick Look). На windows-latest: cargo test --locked (тесты perf_probe пропускаются), затем scripts/check-windows.py для отладочного исполняемого файла. На ubuntu-22.04: cargo build --locked |
release.yml | Тег, совпадающий с v*, или ручной запуск с версией | Три сборки: aarch64-apple-darwin, подписанная и нотаризованная через package-macos.sh в ducklocal-macos-arm64.dmg; Linux на Ubuntu 22.04 в ducklocal-linux-x86_64.tar.gz; Windows в ducklocal-windows-x86_64.zip, после того как scripts/check-windows.py проверит исполняемый файл выпуска. Задание выпуска ждёт все три — падение любого из них проваливает выпуск — и создаёт релиз на GitHub со сгенерированными заметками |
gh-pages.yml | Push в main, затрагивающий скрипт перенаправления или рабочий процесс, либо ручной запуск | Публикует перенаправления со старых адресов jetsquirrel.github.io/DuckLocal/ на новый сайт в GitHub Pages |
Сборке выпуска нужны такие секреты репозитория: MACOS_CERTIFICATE, MACOS_CERTIFICATE_PWD, NOTARY_KEY_BASE64, NOTARY_KEY_ID и NOTARY_ISSUER.
Поддержка платформ
| Платформа | Пакет | Примечания |
|---|---|---|
| macOS 12+, Apple silicon | .dmg, подписанный и нотаризованный, с расширением Quick Look | Проверяется в CI, включая крейт Quick Look |
| Linux x86_64 | .tar.gz с бинарным файлом | Собран на Ubuntu 22.04, для glibc, достаточно старой для большинства дистрибутивов, с системными библиотеками, которые ставит собственный CI gpui-kit |
| Windows x86_64 | .zip с ducklocal.exe | Проверяется в CI. Без подписи кода: сертификата Windows нет, поэтому SmartScreen предупреждает при первом запуске |
Тесты выполняются в macOS и Windows; Linux компилируется при каждом pull request, но не тестируется. Windows запускает их потому, что именно его пути — буквы дисков, \, отсутствие $HOME — это то место, где запуск в macOS не поймает ошибку. Затем scripts/check-windows.py (Python из стандартной библиотеки, запускается в Windows) проверяет исполняемый файл, не запуская графический интерфейс: подсистему GUI, чтобы не открывалось окно консоли; встроенный значок утки; и то, что --version и query печатают в перенаправленный вывод. Сборки для Mac на Intel нет.
Сочетания клавиш привязаны через модификатор secondary gpui — ⌘ в macOS, Ctrl в Windows и Linux. cmd в Windows и Linux был бы клавишей Windows, что сделало бы все сочетания недоступными.
Сайт документации
Сайт живёт в отдельном репозитории, JetSquirrel/ducklocal-site, и обслуживается Cloudflare Workers как статические ресурсы:
| Адрес | Что | Источник |
|---|---|---|
| ducklocal.app | Страница продукта | home/, статические HTML и CSS |
| ducklocal.app/docs | Эти руководства, на английском и китайском | docs/, сайт на VitePress |
Изменение в приложении, которое меняет то, что говорят руководства, требует pull request в оба репозитория. Чтобы работать над руководствами локально, нужны Node.js 22 или новее (рекомендуется 24 LTS) и клон репозитория сайта. Затем выполните:
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Старый адрес GitHub Pages, jetsquirrel.github.io/DuckLocal/, сохраняется как набор перенаправлений на соответствующие новые страницы; gh-pages.yml этого репозитория их публикует.
Структура проекта
| Путь | Содержимое |
|---|---|
src/main.rs | Точка входа, ранняя диспетчеризация CLI, настройка окна GUI |
src/cli.rs | Аргументы без интерфейса, проверка парсером DuckDB, изолированные соединения, ошибки JSON и подсказки к ним |
tests/cli.rs | Интеграционные тесты с реальным исполняемым файлом; временные данные в target/cli-tests |
skills/ducklocal/ | Официальный навык SQL-агента, начинающий со схемы, и справочник по CLI |
src/sources.rs | Преобразование путей в файлы для присоединения и базы данных для открытия |
src/db.rs | Соединение DuckDB, присоединение файлов, сведения о сервере |
src/query.rs | Выполнение запросов, сериализация результатов, экспорт, EXPLAIN и профиль EXPLAIN ANALYZE за кнопкой Profile |
src/script.rs | Разбиение текста редактора на инструкции, которые выполняет Run, включая команды с точкой |
src/overview.rs | Вкладка Overview в результатах: статистика и распределения по столбцам |
src/extensions.rs | Вкладка Extensions на боковой панели: список, INSTALL, LOAD и UPDATE EXTENSIONS |
src/storage.rs | Чтение заголовка файла .duckdb: почему файл не открывается и какой DuckDB читает тот, что открывается |
src/schema_cli.rs | ducklocal schema: отношения и столбцы для запроса, в размере, подходящем для промпта |
src/profile.rs | Статистика столбцов за ducklocal schema --stats |
src/remote.rs | ducklocal open: канал loopback к работающему окну в обе стороны |
src/schema.rs | Интроспекция каталога для боковой панели |
src/spec/ | Дашборды .dash: парсер, проверка, источники, фильтры, комментарии к обзору (ducklocal comments), ducklocal lsp и вкладка дашборда с его графиками |
src/excel.rs | Книги Excel и ODS, загружаемые как одна таблица на лист |
src/setup.rs | Command line & AI…: помещение ducklocal в PATH и установка навыка для агентов |
src/recents.rs | Недавно открытые дашборды, которые перечисляет боковая панель |
src/history.rs | Собственная база данных приложения: история, зарегистрированные файлы, присоединённые базы данных, настройки |
src/s3.rs | Подпись SigV4 и перечисление S3 |
src/i18n.rs | Таблица строк и выбор языка |
src/state.rs | Состояние приложения, общее для разных представлений |
src/ui/ | Редактор, таблица результатов, графики и карты (с тайлами OpenStreetMap), боковая панель, диалоги, строки заголовка и состояния, проверка обновлений |
src/windows.rs | Запуск в Windows: консоль вызывающего процесса для команд CLI, никакой для запуска GUI |
quicklook/ | Предварительный просмотр macOS Quick Look: библиотека Rust, с которой связывается расширение Swift, собирается через scripts/build-quicklook.sh |
src/assets.rs | Значки, встроенные дополнительно к стандартным из библиотеки компонентов |
src/perf_probe.rs | Тестовый стенд для замера производительности: реальное время, число аллокаций и байты для путей, масштабирующихся с размером данных |
assets/ | Значки (.icns, .ico для Windows и скрипт ресурсов), Info.plist с типами документов, которые Finder открывает в DuckLocal, схема, используемая в README и документации |
scripts/ | bundle.sh, build-quicklook.sh, package-macos.sh, check-deps.sh, check-windows.py, make-icons.py, entitlements |
Замечания о тестировании
Набор тестов — это cargo test --workspace; обычный cargo test охватывает приложение, но не крейт quicklook/. Тесты выполнения запросов проверяют DuckDB через соединение в памяти; тесты экспорта охватывают и CSV, и Parquet, причём последний — чтением записанного файла обратно через read_parquet.
