Перейти к содержимому

Разработка ​

Сборка и запуск ​

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

Поскольку 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, и сборка падает с ошибками несовпадения трейтов, которые не называют настоящую причину.

bash
./scripts/check-deps.sh

Он проверяет то, что Cargo не проверяет: одну ревизию во всех зависимостях от репозитория, Cargo.lock, который с ней согласуется, и отсутствие какого-либо крейта в сборке дважды — один раз из репозитория и один раз из crates.io. Он читает два манифеста и больше ничего, поэтому работает офлайн и сразу. CI запускает его перед тестами. Чтобы перейти на более новый набор инструментов, измените все rev в Cargo.toml вместе, выполните cargo update и запустите скрипт.

Закрепление на ревизии git — ещё и причина, по которой крейт DuckLocal нельзя опубликовать на crates.io: там git-зависимость отклоняется. Распространение идёт через пакеты выпуска, описанные ниже.

Упаковка приложения для macOS ​

bash
./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 для песочницы.
bash
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 находит расширение, когда приложение уже запускалось или было зарегистрировано.

Упаковка, подпись и нотаризация ​

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

Запускайте его из корня репозитория; он записывает DuckLocal.app и dmg-root в рабочий каталог, а dmg — рядом с ними. Скрипт отказывается работать без учётных данных: артефакт без нотаризации пользователь не сможет открыть в актуальной macOS, поэтому скрипт быстро падает, а не создаёт его случайно.

Требуется:

ПеременнаяЗначение
NOTARY_KEYПуть к ключу API App Store Connect (.p8)
NOTARY_KEY_IDKey ID этого ключа
NOTARY_ISSUERUUID издателя, которому принадлежит ключ
идентичность Developer ID ApplicationОпределяется автоматически, когда в связке ключей ровно одна; иначе задайте MACOS_SIGN_IDENTITY

Скрипт выполняет такие шаги:

  1. Собирает пакет приложения со штампом версии из аргумента.
  2. Собирает расширение Quick Look через build-quicklook.sh, подписанное Developer ID и собственными entitlements песочницы расширения — никогда scripts/entitlements.plist, потому что расширение приложения должно быть в песочнице, а само приложение — нет.
  3. Подписывает изнутри наружу и без --deep: сначала внутренний исполняемый файл, затем приложение с --options runtime --timestamp и scripts/entitlements.plist, и проверяет результат с помощью codesign --verify --deep --strict.
  4. Собирает dmg UDZO с символической ссылкой на /Applications.
  5. Подписывает сам dmg.
  6. Отправляет его через notarytool submit --wait --timeout 300m.
  7. Прикрепляет тикет.
  8. Завершает stapler validate и двумя проверками spctl --assess.

Две вещи, которые стоит знать перед использованием:

  • Пятичасовой тайм-аут — это ожидание на стороне клиента, а не отмена. Если он истечёт, отправка продолжит обрабатываться на стороне Apple, и тикет можно получить позже, — но тикет привязан к точным отправленным байтам, поэтому не пересобирайте; прикрепляйте тикет к тому файлу, который отправили.
  • Нотаризация выполняется только для dmg, поэтому внутренний .app не несёт прикреплённого тикета. Первому запуску с только что смонтированного образа нужна сеть для связи с Apple.

Entitlement com.apple.security.cs.disable-library-validation необходим, потому что DuckDB делает dlopen своих расширений — в том числе httpfs.

CI и выпуски ​

Рабочий процессТриггерЧто делает
ci.ymlPush в 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.ymlPush в 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) и клон репозитория сайта. Затем выполните:

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

Старый адрес 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.rsducklocal schema: отношения и столбцы для запроса, в размере, подходящем для промпта
src/profile.rsСтатистика столбцов за ducklocal schema --stats
src/remote.rsducklocal open: канал loopback к работающему окну в обе стороны
src/schema.rsИнтроспекция каталога для боковой панели
src/spec/Дашборды .dash: парсер, проверка, источники, фильтры, комментарии к обзору (ducklocal comments), ducklocal lsp и вкладка дашборда с его графиками
src/excel.rsКниги Excel и ODS, загружаемые как одна таблица на лист
src/setup.rsCommand 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.

Опубликовано под лицензией Apache-2.0.