Windows + WSL2 上の Beadbox

プロジェクトが WSL2 上 — つまり \\wsl.localhost\ または \\wsl$\ 配下のいずれか — にある場合は、WSL 内に Linux 版 Beadbox をインストールし、WSLg 経由で起動してください。Windows ネイティブの .exe は WSL2 パスに対してはサポートされていません。本ガイドは Ubuntu 24.04 LTS を対象としています。22.04 はサポート対象外です (Prerequisites を参照)。

なぜ WSL 内で Linux 版 Beadbox を使うのか

ワークスペースが \\wsl.localhost\Ubuntu\home\you\my-project のようなパスにある場合、Windows 上で動く Beadbox.exe は bd CLI を呼び出すたびに 9P ファイルシステムブリッジを越えてアクセスする必要があります。bd CLI は呼び出しごとに Go ランタイムを起動し、組み込み Dolt ストアを再初期化しますが、WSL2 内の Linux カーネルが要求する flock() セマンティクスを Windows 側は確実には満たせません。

結果として 2 つの障害モードが発生します。ウォーム呼び出しでも約 1240 ms (Beadbox の 500 ms ポーリング枠を大きく超過) かかること、そしてワークスペースに 2 つのプロセスが同時に触れたときに断続的に発生する flock エラーです。よりすっきりした解決策は、ワークスペースが既に存在している場所 — つまり WSL2 内 — で Beadbox を実行し、GUI の描画は WSLg に任せることです。

前提条件

本ガイドは WSL2 上の Ubuntu 24.04 LTS を対象としています。Ubuntu 22.04 では動作しません — Beadbox の .deb は libwebkit2gtk-4.1 に依存しており、これは 24.04 以降でのみネイティブに提供されているためです。それ以前の WSL2 ディストロではインストール時に依存関係エラーで失敗します。

ステップ 1 の前に、2 つの前提条件があります:

WSL1 ではなく WSL2 をデフォルトにします。WSLg は WSL2 上でしか GUI アプリを描画しません。ディストロをインストールする前に、PowerShell で 1 度だけ次を実行します:
```
wsl --set-default-version 2
```
Ubuntu 24.04 をインストールします (または既存のディストロをアップグレードします)。このステップは対話的です — イメージのダウンロードに数分かかり、完了時に Linux のユーザー名とパスワードの作成を求められます:
```
wsl --install Ubuntu-24.04
```
ディストロが WSL2 上で動作していることを確認します:
```
wsl --list --verbose
```

出力に Ubuntu-24.04 の隣に VERSION 2 と表示されているはずです。1 と表示された場合は、次のコマンドで変換します: wsl --set-version Ubuntu-24.04 2。

WSL2 に Linux 版 Beadbox をインストール

以下のコマンドは Ubuntu 24.04 の WSL2 ターミナル内で実行します。PowerShell から wsl -d Ubuntu-24.04 でターミナルを開くか、Windows Terminal のドロップダウンからディストロを選んでください。

1. beads CLI をインストール

Beadbox は bd CLI をラップしているため、両方が必要です。まず bd をインストールします:

curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

bd --version で確認します。bd のバージョン文字列が表示されるはずです。

2. Beadbox の .deb をダウンロード

GitHub releases から最新の Linux .deb を取得します:

VER=$(curl -sSL https://api.github.com/repos/beadbox/beadbox/releases/latest | sed -n 's/.*"tag_name":[[:space:]]*"v\{0,1\}\([^"]*\)".*/\1/p')
curl -L -o beadbox.deb "https://github.com/beadbox/beadbox/releases/download/v${VER}/beadbox_${VER}_Linux_amd64.deb"

3. .deb をインストール

まず apt インデックスを更新します — 新しい WSL2 ディストロは古いパッケージリストのまま出荷されており、そうしないと推移的依存関係で 404 エラーが出てインストールが失敗します。同じ行で .deb をインストールします:

sudo apt-get update && sudo apt install ./beadbox.deb

更新後も apt が依存関係の不足を報告する場合は、sudo apt --fix-broken install を実行してから再度試してください。

WSLg で起動する

WSLg は Windows 10 と 11 の WSL2 に同梱されており、Linux GUI アプリを Windows デスクトップ上で直接描画します。X server のセットアップも追加の設定も不要 — そのままアプリを実行するだけです:

beadbox

初回起動では WSLg がディスプレイをネゴシエートする間、数秒かかることがあります。その後は他のネイティブウィンドウと同じように扱えます: タスクバーにピン留めしたり、Alt-Tab で切り替えたり、モニター間でドラッグできます。ワークスペースを開くときは Linux 側のパス (~/my-project) を指定してください。Windows 側のパスではありません。WSL の中では ~/ が正しいホームです。

ヒント: スタートメニューのショートカットが欲しい場合、.deb は .desktop エントリをインストールするので、Windows が自動的に「Beadbox (Ubuntu)」のような名前で表示します。インストール後にスタートメニューで検索してください。

すでに flock エラーが出てしまった場合

Beadbox.exe をインストールして WSL ワークスペースを開こうとした場合、おそらく flock や組み込みモードの失敗、ワークスペースの読み込み失敗を伝えるエラーを目にしたはずです。修復は単純です:

Beadbox.exe でワークスペースを閉じる (またはアプリ自体を終了する)。Windows ネイティブ版はこのワークスペースに対しては動作しません。
上記のインストール手順を WSL2 ディストロ内で実行し、Linux 版 Beadbox をインストールする。
WSL の中から Beadbox を開き (WSL のターミナルで beadbox を実行)、Linux のパス (~/my-project) を指定してワークスペースを開く。

Windows 側にホストされたプロジェクト (C:\Users\you\my-project のようなパス) のために、Beadbox.exe はそのまま残しておいて構いません。それらに対しては Windows 版で問題ありません — Linux 版が必要なのは WSL でホストされたプロジェクトだけです。

トラブルシューティング

起動時の libEGL / Mesa 警告

beadbox を初めて実行すると、libEGL や Mesa、GL ドライバから、ハードウェアアクセラレーションがない、あるいはソフトウェアレンダリングへフォールバックするといった警告がターミナルに表示されることがあります。これは WSLg 上では正常です — WSL2 は Windows の GPU を Linux 側に直接公開しないため、GUI スタックはソフトウェア経路にフォールバックします。アプリは問題なく起動し、Beadbox 本来のスピードで動作します。これらの警告はノイズであり、エラーではありません。

背景と参考情報

両方のビルド (Windows .exe と Linux .deb) は同じ Beadbox のコードベースから出荷されています。.exe が WSL ワークスペースを駆動できないのは構造的な理由であり、修正予定のバグではありません — レイテンシの計算とファイルシステムブリッジが不利に働いています。

この決定の背景にあるアーキテクチャの詳細を知りたい場合は、却下された経路を排除した設計ドキュメントとレイテンシトレーサーへのリンクが下にあります。