# 開発

> Rust と DuckDB でソースから DuckLocal をビルドし、テストを実行し、macOS アプリをバンドルし、macOS、Linux、Windows 向けにリリースします。

Source: https://ducklocal.app/docs/ja/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 はベンダー化されたソースコードから直接コンパイルされるため、最初のビルドには目に見える時間がかかり、数ギガバイトのディスク容量が必要です。dev プロファイルの依存関係は `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` キーも存在しないため、実質的な下限は依存関係によって決まります。`duckdb` が要求する `1.85.1` です。 CI は素の stable を使います。

## 固定されたツールキット

UI ツールキットである `gpui-kit` は、`longbridge/gpui-kit` リポジトリから取得しており、意図的に単一の git リビジョンに固定されています。2 つのリビジョンを混在させると `gpui-base` のコピーがビルドに 2 つ入り、ビルドは原因を名指ししない trait の不一致エラーで失敗します。

```bash
./scripts/check-deps.sh
```

これは Cargo が行わない検査を行います。そのリポジトリへのすべての依存関係が 1 つのリビジョンを指していること、 `Cargo.lock` がそれと一致していること、そしてビルド内に同じクレートが 2 回（一方はリポジトリから、もう一方は crates.io から）入っていないことです。2 つのマニフェストだけを読み、それ以外は何もしないので、オフラインで即座に終わります。CI はテストの前にこれを実行します。より新しいツールキットに移行するには、`Cargo.toml` 内のすべての `rev` をまとめて変更し、`cargo update` を実行して、スクリプトを実行します。

git リビジョンに固定していることは、DuckLocal クレートを crates.io に公開できない理由でもあります。 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 拡張機能

Finder で Parquet、DuckDB、CSV、TSV、JSON Lines ファイルをスペースキーでプレビューする機能は、アプリの `Contents/PlugIns` にある拡張機能 `DuckLocalPreview.appex` です。2 つの部分から成ります。

- `quicklook/` はワークスペースクレート `ducklocal-quicklook` です。Rust 製のプレビュー
  エンジンで、静的ライブラリとしてビルドされます。アプリと同じバンドル済みの DuckDB（同じロックファイルから取得するので DuckDB のコンパイルは 1 回）でファイルを開き、その列と最初の 50 行を 1 つの自己完結した HTML ページとして描画します。拡張機能は独自のサンドボックス化されたプロセスであり、アプリを呼び出すことはできません。
- `quicklook/extension/` はその周りの Swift のシェルです。`PreviewProvider.swift`、
  C ヘッダー、拡張機能の `Info.plist`（プレビューするコンテンツタイプ）、そしてサンドボックスの entitlement が含まれます。

```bash
scripts/build-quicklook.sh <DuckLocal.app> [signing identity]
```

このスクリプトはエンジンをビルドし（`cargo build --release -p ducklocal-quicklook`、 `RUST_TARGET` が設定されていればリリースワークフローと同様にそのターゲット）、アプリの DuckDB ビルドを再利用します。続いて `swiftc` で Swift のシェルを macOS 12 向けにコンパイルし、アプリのバージョンが刻印された `Info.plist` をコピーし、拡張機能自身の entitlement で `.appex` に署名します。ID がなければアドホック署名です。 `bundle.sh` は ID なしでこれを呼び出します。アプリを起動または登録すると、 macOS が拡張機能を見つけます。

## パッケージ化、署名、公証

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

リポジトリのルートから実行してください。`DuckLocal.app` と `dmg-root` を作業ディレクトリに、 dmg をその隣に書き出します。このスクリプトは認証情報がないと実行を拒否します。公証されていない成果物は、現在の macOS ではユーザーが開けないため、誤って生成するよりも早く失敗させます。

必要なもの：

| 変数 | 意味 |
| --- | --- |
| `NOTARY_KEY` | App Store Connect API キー（`.p8`）へのパス |
| `NOTARY_KEY_ID` | そのキーの Key ID |
| `NOTARY_ISSUER` | そのキーが属する発行者 UUID |
| Developer ID Application の ID | キーチェーンにちょうど 1 つあれば自動検出。それ以外は `MACOS_SIGN_IDENTITY` を設定 |

スクリプトは次の手順を実行します。

1. 引数のバージョンを刻印してバンドルをビルドします。
2. `build-quicklook.sh` で Quick Look 拡張機能をビルドし、Developer ID と
   拡張機能自身のサンドボックス entitlement で署名します。`scripts/entitlements.plist` は決して使いません。アプリ拡張機能はサンドボックス化される必要があり、アプリ本体はそうではないからです。
3. `--deep` を使わずに内側から外側へ、内部の実行ファイル、次にアプリ本体を
   `--options runtime --timestamp` と `scripts/entitlements.plist` で署名し、 `codesign --verify --deep --strict` で結果を検証します。
4. `/Applications` へのシンボリックリンクを含む UDZO 形式の dmg をビルドします。
5. **dmg 自体に署名します**。
6. `notarytool submit --wait --timeout 300m` で提出します。
7. チケットをステープルします。
8. `stapler validate` と 2 つの `spctl --assess` チェックで終了します。

使う前に知っておくべき 2 つのこと：

- 5 時間のタイムアウトはクライアント側の待機であり、キャンセルではありません。期限が
  切れても、提出は Apple 側で処理が続き、チケットは後で回収できます。ただし **チケットは提出した正確なバイト列に結び付きます**。そのため再ビルドせず、提出したファイルをステープルしてください。
- 公証されるのは dmg だけなので、内側の `.app` にはステープルされたチケットがありません。
  マウントしたばかりのイメージから初めて起動するときは、Apple に確認するためのネットワークが必要です。

`com.apple.security.cs.disable-library-validation` の entitlement が必要です。 DuckDB が拡張機能を `dlopen` するためで、その中には `httpfs` も含まれます。

## CI とリリース

| ワークフロー | トリガー | 内容 |
| --- | --- | --- |
| `ci.yml` | `main` へのプッシュ、すべてのプルリクエスト | `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*` に一致するタグ、またはバージョンを指定した手動実行 | 3 つのビルド：`aarch64-apple-darwin` を `package-macos.sh` で署名・公証して `ducklocal-macos-arm64.dmg` に。Ubuntu 22.04 上の Linux を `ducklocal-linux-x86_64.tar.gz` に。Windows は `scripts/check-windows.py` がリリース版実行ファイルを検証した後、`ducklocal-windows-x86_64.zip` に。リリースジョブは 3 つすべてを待ち、1 つでも失敗すればリリースは失敗します。そして自動生成されたノートで GitHub リリースを作成します |
| `gh-pages.yml` | リダイレクトスクリプトまたはワークフローに触れる `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 向けで、gpui-kit 自身の CI がインストールするシステムライブラリを使用 |
| Windows x86_64 | `ducklocal.exe` の `.zip` | CI でテスト済み。コード署名はありません。Windows 証明書がないため、初回起動時に SmartScreen が警告します |

テストは macOS と Windows で実行されます。Linux はすべてのプルリクエストでコンパイルされますが、テストはされません。Windows でテストするのは、そのパス（ドライブレター、`\`、`$HOME` がないこと）が、macOS での実行では見つけられない間違いの場所だからです。次に `scripts/check-windows.py`（標準ライブラリのみの Python、Windows で実行）が GUI を起動せずに実行ファイルを検査します。GUI サブシステムであること（コンソールウィンドウが開かないこと）、埋め込まれたアヒルのアイコン、そして `--version` と `query` がリダイレクトされた出力に書き出すことを確認します。Intel Mac 向けのビルドはありません。

ショートカットは gpui の `secondary` 修飾キーで割り当てられています。macOS では ⌘、 Windows と Linux では Ctrl です。`cmd` を使うと Windows と Linux では Windows キーになり、すべてのショートカットに到達できなくなります。

## ドキュメントサイト

Web サイトは独自のリポジトリ [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/) サイト |

ガイドの内容を変えるアプリの変更には、両方のリポジトリへのプルリクエストが必要です。ガイドをローカルで作業するための前提は、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、そして **Profile** の背後の EXPLAIN ANALYZE プロファイル |
| `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`：実行中のウィンドウへのループバックチャネル（双方向） |
| `src/schema.rs` | サイドバー向けのカタログの内部調査 |
| `src/spec/` | `.dash` ダッシュボード：パーサー、検証、ソース、フィルター、レビューコメント（`ducklocal comments`）、`ducklocal lsp`、プロット付きのダッシュボードタブ |
| `src/excel.rs` | Excel と ODS のワークブック。シートごとに 1 つのテーブルとして読み込みます |
| `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 プレビュー：Swift 拡張機能がリンクする Rust ライブラリで、`scripts/build-quicklook.sh` がビルドします |
| `src/assets.rs` | コンポーネントライブラリのデフォルトを超えて埋め込まれるアイコン |
| `src/perf_probe.rs` | テスト専用のパフォーマンスプローブハーネス：データサイズに比例する処理の実時間、アロケーション回数、バイト数 |
| `assets/` | アイコン（`.icns`、Windows の `.ico` とリソーススクリプト）、Finder が DuckLocal で開くドキュメントタイプを含む `Info.plist`、README とドキュメントが使う図 |
| `scripts/` | `bundle.sh`、`build-quicklook.sh`、`package-macos.sh`、`check-deps.sh`、`check-windows.py`、`make-icons.py`、entitlement |

## テストに関するメモ

テストスイートは `cargo test --workspace` です。素の `cargo test` はアプリを対象にしますが、 `quicklook/` クレートは含みません。クエリ実行のテストはメモリ内の接続を通じて DuckDB を動かします。エクスポートのテストは CSV と Parquet の両方を対象とし、後者は書き出したファイルを `read_parquet` で読み返して検証します。
