開発
ビルドと実行
cargo run # empty in-memory workspace
cargo run -- ./data/logs/ # open something straight away
cargo test --workspace # run the test suite, Quick Look engine includedDuckDB はベンダー化されたソースコードから直接コンパイルされるため、最初のビルドには目に見える時間がかかり、数ギガバイトのディスク容量が必要です。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 の不一致エラーで失敗します。
./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 アプリをバンドルする
./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 が含まれます。
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 が拡張機能を見つけます。
パッケージ化、署名、公証
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 を設定 |
スクリプトは次の手順を実行します。
- 引数のバージョンを刻印してバンドルをビルドします。
build-quicklook.shで Quick Look 拡張機能をビルドし、Developer ID と 拡張機能自身のサンドボックス entitlement で署名します。scripts/entitlements.plistは決して使いません。アプリ拡張機能はサンドボックス化される必要があり、アプリ本体はそうではないからです。--deepを使わずに内側から外側へ、内部の実行ファイル、次にアプリ本体を--options runtime --timestampとscripts/entitlements.plistで署名し、codesign --verify --deep --strictで結果を検証します。/Applicationsへのシンボリックリンクを含む UDZO 形式の dmg をビルドします。- dmg 自体に署名します。
notarytool submit --wait --timeout 300mで提出します。- チケットをステープルします。
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 にあり、 Cloudflare Workers によって静的アセットとして配信されています。
| アドレス | 内容 | ソース |
|---|---|---|
| ducklocal.app | 製品ページ | home/、静的な HTML と CSS |
| ducklocal.app/docs | このガイド(英語と中国語) | docs/、VitePress サイト |
ガイドの内容を変えるアプリの変更には、両方のリポジトリへのプルリクエストが必要です。ガイドをローカルで作業するための前提は、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、そして 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 で読み返して検証します。
