# Разработка

> Соберите DuckLocal из исходного кода с Rust и DuckDB, запустите тесты, упакуйте приложение для macOS и выпустите версию для macOS, Linux и Windows.

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

## Сборка и запуск {#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
```

Поскольку 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_ID` | Key ID этого ключа |
| `NOTARY_ISSUER` | UUID издателя, которому принадлежит ключ |
| идентичность 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.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](https://github.com/JetSquirrel/ducklocal-site),
и обслуживается Cloudflare Workers как статические ресурсы:

| Адрес | Что | Источник |
| --- | --- | --- |
| [ducklocal.app](https://ducklocal.app/) | Страница продукта | `home/`, статические HTML и CSS |
| [ducklocal.app/docs](https://ducklocal.app/docs/) | Эти руководства, на английском и китайском | `docs/`, сайт на [VitePress](https://vitepress.dev/) |

Изменение в приложении, которое меняет то, что говорят руководства, требует 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.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`.
