Beadbox su Windows + WSL2

Perché Beadbox per Linux in WSL

Quando il tuo workspace si trova in un percorso come \\wsl.localhost\Ubuntu\home\you\my-project, Beadbox.exe in esecuzione su Windows deve attraversare il bridge del file system 9P a ogni invocazione del CLI bd. Il CLI bd avvia un runtime Go e re-inizializza l'archivio Dolt incorporato a ogni chiamata, e il kernel Linux dentro WSL2 applica una semantica flock() che il lato Windows non può rispettare in modo affidabile.

Il risultato sono due modalità di errore: chiamate a caldo misurate intorno ai 1240 ms (ben oltre la finestra di polling di 500 ms di Beadbox) ed errori flock intermittenti quando due processi toccano il workspace contemporaneamente. La soluzione più pulita è eseguire Beadbox dove vive già il workspace — dentro WSL2 — e lasciare che WSLg renderizzi la GUI su Windows.

Prerequisiti

Questa guida è pensata per Ubuntu 24.04 LTS dentro WSL2. Ubuntu 22.04 non funzionerà — il .deb di Beadbox dipende da libwebkit2gtk-4.1, che è disponibile in modo nativo solo su 24.04 e versioni successive. Le distribuzioni WSL2 più vecchie falliranno al passo di installazione con un errore di dipendenze non soddisfatte.

Due prerequisiti prima del Passo 1:

1. Imposta WSL2 come predefinito, non WSL1. WSLg renderizza le app GUI solo su WSL2. Esegui questo comando una volta in PowerShell prima di installare la distribuzione:

   wsl --set-default-version 2

2. Installa Ubuntu 24.04 (o aggiorna una distribuzione esistente). Questo passaggio è interattivo — il download dell'immagine richiede qualche minuto e ti verrà chiesto di creare un nome utente e una password Linux al termine:

   wsl --install Ubuntu-24.04

3. Verifica che la distribuzione sia su WSL2:

   wsl --list --verbose

L'output dovrebbe mostrare VERSION 2 accanto a Ubuntu-24.04. Se mostra 1, convertila: wsl --set-version Ubuntu-24.04 2.

Installare Beadbox per Linux in WSL2

Questi comandi vanno eseguiti dentro il terminale WSL2 di Ubuntu 24.04. Aprine uno con wsl -d Ubuntu-24.04 da PowerShell, oppure scegli la distribuzione dal menu a tendina di Windows Terminal.

1. Installa il CLI beads

Beadbox avvolge il CLI bd, quindi ti servono entrambi. Installa prima bd:

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

Verifica con bd --version. Dovresti vedere la stringa di versione di bd.

2. Scarica il .deb di Beadbox

Prendi l'ultimo .deb per Linux dalle release su GitHub:

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. Installa il .deb

Aggiorna prima l'indice di apt — le distribuzioni WSL2 nuove di zecca arrivano con un elenco pacchetti obsoleto e altrimenti l'installazione fallisce con errori 404 sulle dipendenze transitive. Poi installa il .deb sulla stessa riga:

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

Se apt segnala ancora dipendenze mancanti dopo l'aggiornamento, esegui sudo apt --fix-broken install e riprova.

Avviare con WSLg

WSLg è incluso con WSL2 su Windows 10 e 11 e renderizza le app GUI Linux direttamente sul desktop Windows. Nessuna configurazione di X server, nessuna config aggiuntiva — basta avviare l'app:

beadbox

Il primo avvio può richiedere qualche secondo mentre WSLg negozia il display. Dopodiché, Beadbox si comporta come qualsiasi altra finestra nativa: appuntala alla taskbar, alt-tab su di lei, trascinala tra i monitor. Quando apri un workspace, puntalo al percorso lato Linux (~/my-project), non al percorso lato Windows. Dentro WSL, ~/ è la home corretta.

Suggerimento: se vuoi un collegamento nel menu Start, il .deb installa una voce .desktop che Windows mostra automaticamente come "Beadbox (Ubuntu)" o simile. Cercala nel menu Start dopo l'installazione.

Hai già incontrato l'errore flock?

Se hai installato Beadbox.exe e hai provato ad aprire un workspace WSL, probabilmente hai visto un errore che menziona flock, un fallimento in modalità incorporata o un workspace che non si carica. La soluzione è semplice:

1. Chiudi il workspace in Beadbox.exe (o esci completamente dall'app). La build nativa per Windows non funzionerà su questo workspace.
2. Segui i passaggi di installazione qui sopra dentro la tua distribuzione WSL2 per installare Beadbox per Linux.
3. Apri Beadbox da dentro WSL (esegui beadbox nel terminale WSL) e apri il workspace usando il suo percorso Linux (~/my-project).

Puoi tenere installato Beadbox.exe per i progetti ospitati lato Windows (percorsi tipo C:\Users\you\my-project). La build per Windows va bene per quelli — sono solo i progetti ospitati in WSL ad aver bisogno della build per Linux.

Risoluzione dei problemi

Avvisi libEGL / Mesa all'avvio

Quando esegui beadbox per la prima volta, il terminale potrebbe stampare avvisi da libEGL, Mesa o dai driver GL riguardo all'accelerazione hardware mancante o al fallback al rendering software. È normale sotto WSLg — WSL2 non espone direttamente la tua GPU Windows al lato Linux, quindi lo stack GUI ricade su percorsi software. L'app si avvia regolarmente e gira alla piena velocità di Beadbox; gli avvisi sono rumore, non errori.

Contesto e riferimenti

Entrambe le build (.exe per Windows e .deb per Linux) partono dallo stesso codebase di Beadbox. Il motivo per cui il .exe non può pilotare un workspace WSL è strutturale, non un bug che intendiamo correggere — la matematica della latenza e il bridge del file system giocano contro.

Se vuoi i dettagli architetturali dietro questa decisione, i design brief e il tracer di latenza che hanno scartato i percorsi alternativi sono linkati qui sotto.

• Beadbox issues on GitHub
• beads CLI repository
• Microsoft: Run Linux GUI apps with WSLg