コンテンツへスキップ

開発 ​

ビルドと実行 ​

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_KEYApp 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.ymlmain へのプッシュ、すべてのプルリクエスト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.ymlv* に一致するタグ、またはバージョンを指定した手動実行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.gzUbuntu 22.04 でビルド。ほとんどのディストリビューションで使える十分に古い glibc 向けで、gpui-kit 自身の CI がインストールするシステムライブラリを使用
Windows x86_64ducklocal.exe の .zipCI でテスト済み。コード署名はありません。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 を推奨)と、サイトリポジトリのクローンです。その後、次を実行します。

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.rsDuckDB 接続、ファイルのアタッチ、サーバー情報
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.rsducklocal schema:クエリ対象のリレーションと列を、プロンプト向けのサイズで出力
src/profile.rsducklocal schema --stats の背後の列統計
src/remote.rsducklocal open:実行中のウィンドウへのループバックチャネル(双方向)
src/schema.rsサイドバー向けのカタログの内部調査
src/spec/.dash ダッシュボード:パーサー、検証、ソース、フィルター、レビューコメント(ducklocal comments)、ducklocal lsp、プロット付きのダッシュボードタブ
src/excel.rsExcel と ODS のワークブック。シートごとに 1 つのテーブルとして読み込みます
src/setup.rsCommand line & AI…:ducklocal を PATH に追加し、エージェントスキルをインストールします
src/recents.rsサイドバーに一覧される、最近開いたダッシュボード
src/history.rsアプリ自身のデータベース:履歴、登録されたファイル、アタッチされたデータベース、設定
src/s3.rsSigV4 署名と S3 の一覧取得
src/i18n.rs文字列テーブルと言語の選択
src/state.rsビュー間で共有されるアプリケーションの状態
src/ui/エディタ、結果グリッド、グラフと地図(OpenStreetMap のタイルを含む)、サイドバー、ダイアログ、タイトルバーとステータスバー、更新の確認
src/windows.rsWindows での起動: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 で読み返して検証します。

Apache-2.0 ライセンスで公開されています。