Windows + WSL2 पर Beadbox

अगर आपका project WSL2 में है — कहीं भी \\wsl.localhost\ या \\wsl$\ के अंदर — तो WSL के अंदर Linux Beadbox install करें और उसे WSLg के ज़रिए launch करें। Native Windows .exe WSL2 paths के साथ supported नहीं है। यह guide Ubuntu 24.04 LTS को target करती है; 22.04 supported नहीं है (Prerequisites देखें)।

WSL में Linux Beadbox क्यों

जब आपका workspace \\wsl.localhost\Ubuntu\home\you\my-project जैसे path पर हो, तो Windows पर चल रहे Beadbox.exe को हर bd CLI invocation के लिए 9P file-system bridge के पार पहुँचना पड़ता है। bd CLI हर call पर एक Go runtime bootstrap करता है और embedded Dolt store को फिर से initialize करता है, और WSL2 के अंदर का Linux kernel flock() semantics enforce करता है जिन्हें Windows side reliably honour नहीं कर सकता।

नतीजा दो failure modes हैं: warm calls करीब 1240 ms पर मापे गए (Beadbox के 500 ms polling envelope से कहीं ज़्यादा), और intermittent flock errors जब दो processes एक साथ workspace को touch करते हैं। साफ़ जवाब है Beadbox को वहीं चलाना जहाँ workspace पहले से है — WSL2 के अंदर — और WSLg को Windows पर GUI render करने देना।

Prerequisites

यह guide WSL2 के अंदर Ubuntu 24.04 LTS को target करती है। Ubuntu 22.04 काम नहीं करेगा — Beadbox .deb libwebkit2gtk-4.1 पर depend करता है, जो natively सिर्फ़ 24.04 और बाद के versions में ship होता है। पुराने WSL2 distros install step पर unmet-dependency error के साथ fail होंगे।

Step 1 से पहले दो prerequisites:

  1. Default WSL2 रखें, WSL1 नहीं। WSLg सिर्फ़ WSL2 पर GUI apps render करता है। Distro install करने से पहले PowerShell में यह एक बार चलाएँ:

    wsl --set-default-version 2

  2. Ubuntu 24.04 install करें (या किसी मौजूदा distro को upgrade करें)। यह step interactive है — image download में कुछ minutes लगते हैं, और जब वह पूरा होगा तब आपसे एक Linux username और password बनाने को कहा जाएगा:

    wsl --install Ubuntu-24.04

  3. Verify करें कि distro WSL2 पर है:

    wsl --list --verbose

Output में Ubuntu-24.04 के बगल में VERSION 2 दिखना चाहिए। अगर 1 दिखे, तो उसे convert करें: wsl --set-version Ubuntu-24.04 2।

WSL2 में Linux Beadbox install करें

ये commands आपके Ubuntu 24.04 WSL2 terminal के अंदर चलते हैं। PowerShell से wsl -d Ubuntu-24.04 के साथ एक खोलें, या Windows Terminal dropdown से distro चुनें।

1. beads CLI install करें

Beadbox bd CLI को wrap करता है, इसलिए दोनों चाहिए। पहले bd install करें:

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

bd --version से verify करें। आपको bd version string दिखनी चाहिए।

2. Beadbox .deb download करें

GitHub releases से latest 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 install करें

पहले apt index refresh करें — fresh WSL2 distros stale package list के साथ ship होते हैं और वरना install transitive dependencies पर 404s के साथ fail हो जाएगा। फिर उसी line में .deb install करें:

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

अगर refresh के बाद भी apt missing dependencies report करे, तो sudo apt --fix-broken install चलाएँ और फिर से try करें।

WSLg के ज़रिए launch करें

WSLg Windows 10 और 11 पर WSL2 के साथ ship होता है और Linux GUI apps को सीधे आपके Windows desktop पर render करता है। कोई X server setup नहीं, कोई extra config नहीं — बस app चलाएँ:

beadbox

पहली launch में WSLg के display negotiate करते समय कुछ seconds लग सकते हैं। इसके बाद Beadbox किसी भी native window की तरह behave करता है: इसे taskbar पर pin करें, alt-tab करें, monitors के बीच drag करें। जब आप कोई workspace खोलें, तो उसे Linux-side path (~/my-project) पर point करें, Windows-side path पर नहीं। WSL के अंदर ~/ ही सही home है।

Tip: अगर आपको Start-menu shortcut चाहिए, तो .deb एक .desktop entry install करता है जिसे Windows अपने आप "Beadbox (Ubuntu)" या जैसा कुछ surface कर देता है। Install के बाद Start menu में इसे search करें।

क्या आपको पहले ही flock error मिल चुकी है?

अगर आपने Beadbox.exe install किया और WSL workspace खोलने की कोशिश की, तो आपको शायद flock, embedded-mode failure, या workspace load न होने का error दिखा होगा। Fix सीधा है:

  1. Beadbox.exe में workspace बंद करें (या app पूरी तरह quit कर दें)। Native Windows build इस workspace के साथ काम नहीं करेगा।
  2. Linux Beadbox install करने के लिए ऊपर दिए install steps अपने WSL2 distro के अंदर follow करें।
  3. WSL के अंदर से Beadbox खोलें (WSL terminal में beadbox चलाएँ) और workspace को उसके Linux path (~/my-project) से खोलें।

आप Windows side पर hosted projects (C:\Users\you\my-project जैसे paths) के लिए Beadbox.exe install रख सकते हैं। उन के लिए Windows build ठीक है — सिर्फ़ WSL-hosted projects को Linux build चाहिए।

Troubleshooting

Launch पर libEGL / Mesa warnings

जब आप पहली बार beadbox चलाते हैं, तो terminal पर libEGL, Mesa, या GL drivers से missing hardware acceleration या software rendering पर fallback के बारे में warnings print हो सकती हैं। ये WSLg के नीचे normal हैं — WSL2 आपकी Windows GPU को सीधे Linux side पर expose नहीं करता, इसलिए GUI stack software paths पर fall back कर जाता है। App ठीक से launch होता है और पूरी Beadbox speed पर चलता है; warnings noise हैं, errors नहीं।

Background और references

दोनों builds (Windows .exe और Linux .deb) एक ही Beadbox codebase से ship होते हैं। .exe WSL workspace drive क्यों नहीं कर सकता, यह structural reason है, कोई bug नहीं जिसे हम fix करने वाले हैं — latency math और file-system bridge इसके खिलाफ़ stacked हैं।

अगर आप इस decision के पीछे architectural detail चाहते हैं, तो design briefs और latency tracer (जिसने rejected paths को ruled out किया) नीचे linked हैं।