Beadbox sur Windows + WSL2

Si votre projet vit dans WSL2 — n'importe où sous \\wsl.localhost\ ou \\wsl$\ — installez Beadbox Linux dans WSL et lancez-le via WSLg. Le .exe natif Windows n'est pas pris en charge sur les chemins WSL2. Ce guide cible Ubuntu 24.04 LTS ; 22.04 n'est pas pris en charge (voir Prérequis).

Pourquoi Beadbox Linux dans WSL

Lorsque votre workspace vit à un chemin comme \\wsl.localhost\Ubuntu\home\you\my-project, Beadbox.exe sous Windows doit traverser le pont de système de fichiers 9P à chaque invocation du CLI bd. Le CLI bd amorce un runtime Go et réinitialise le store Dolt embarqué à chaque appel, et le noyau Linux à l'intérieur de WSL2 applique une sémantique flock() que le côté Windows ne peut pas honorer de manière fiable.

Le résultat : deux modes de défaillance — des appels à chaud mesurés autour de 1240 ms (bien au-delà de l'enveloppe de polling de 500 ms de Beadbox), et des erreurs flock intermittentes lorsque deux processus touchent le workspace en même temps. La réponse plus propre est d'exécuter Beadbox là où le workspace vit déjà — à l'intérieur de WSL2 — et de laisser WSLg afficher le GUI sur Windows.

Prérequis

Ce guide cible Ubuntu 24.04 LTS dans WSL2. Ubuntu 22.04 ne fonctionnera pas — le .deb de Beadbox dépend de libwebkit2gtk-4.1, qui n'est livré nativement qu'à partir de 24.04. Les distributions WSL2 plus anciennes échoueront à l'étape d'installation avec une erreur de dépendance non satisfaite.

Deux prérequis avant l'étape 1 :

  1. Définir WSL2 par défaut, pas WSL1. WSLg n'affiche les applications GUI que sur WSL2. Exécutez ceci une fois dans PowerShell avant d'installer la distribution :

    wsl --set-default-version 2

  2. Installez Ubuntu 24.04 (ou mettez à niveau une distribution existante). Cette étape est interactive — le téléchargement de l'image prend quelques minutes, et il vous sera demandé de créer un nom d'utilisateur et un mot de passe Linux à la fin :

    wsl --install Ubuntu-24.04

  3. Vérifiez que la distribution est bien sur WSL2 :

    wsl --list --verbose

La sortie devrait afficher VERSION 2 à côté de Ubuntu-24.04. Si elle affiche 1, convertissez-la : wsl --set-version Ubuntu-24.04 2.

Installer Beadbox Linux dans WSL2

Ces commandes s'exécutent dans le terminal Ubuntu 24.04 WSL2. Ouvrez-en un avec wsl -d Ubuntu-24.04 depuis PowerShell, ou choisissez la distribution dans le menu déroulant de Windows Terminal.

1. Installer le CLI beads

Beadbox enveloppe le CLI bd, vous avez donc besoin des deux. Installez d'abord bd :

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

Vérifiez avec bd --version. Vous devriez voir la chaîne de version de bd.

2. Télécharger le .deb de Beadbox

Récupérez le dernier .deb Linux depuis les releases 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. Installer le .deb

Rafraîchissez d'abord l'index apt — les distributions WSL2 fraîches sont livrées avec une liste de paquets obsolète et l'installation échouera sinon avec des 404 sur les dépendances transitives. Ensuite, installez le .deb dans la même ligne :

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

Si apt signale toujours des dépendances manquantes après le rafraîchissement, exécutez sudo apt --fix-broken install et réessayez.

Lancer via WSLg

WSLg est livré avec WSL2 sur Windows 10 et 11 et affiche les applications GUI Linux directement sur votre bureau Windows. Aucune configuration de X server, aucune configuration supplémentaire — il suffit d'exécuter l'application :

beadbox

Le premier lancement peut prendre quelques secondes pendant que WSLg négocie l'affichage. Ensuite, Beadbox se comporte comme n'importe quelle autre fenêtre native : épinglez-la à votre barre des tâches, faites alt-tab vers elle, faites-la glisser entre les écrans. Lorsque vous ouvrez un workspace, pointez-le vers le chemin côté Linux (~/my-project), pas le chemin côté Windows. Dans WSL, ~/ est le bon home.

Astuce : si vous voulez un raccourci dans le menu Démarrer, le .deb installe une entrée .desktop que Windows expose automatiquement comme « Beadbox (Ubuntu) » ou similaire. Cherchez-la dans le menu Démarrer après l'installation.

Vous avez déjà rencontré l'erreur flock ?

Si vous avez installé Beadbox.exe et essayé d'ouvrir un workspace WSL, vous avez probablement vu une erreur mentionnant flock, un échec en mode embarqué, ou le workspace qui ne se charge pas. La solution est simple :

  1. Fermez le workspace dans Beadbox.exe (ou quittez complètement l'application). La build native Windows ne fonctionnera pas avec ce workspace.
  2. Suivez les étapes d'installation ci-dessus dans votre distribution WSL2 pour installer Beadbox Linux.
  3. Ouvrez Beadbox depuis l'intérieur de WSL (exécutez beadbox dans le terminal WSL) et ouvrez le workspace en utilisant son chemin Linux (~/my-project).

Vous pouvez garder Beadbox.exe installé pour les projets hébergés côté Windows (chemins comme C:\Users\you\my-project). La build Windows convient pour ceux-là — seuls les projets hébergés dans WSL ont besoin de la build Linux.

Dépannage

Avertissements libEGL / Mesa au lancement

Lorsque vous exécutez beadbox pour la première fois, le terminal peut afficher des avertissements de libEGL, Mesa ou des pilotes GL concernant l'absence d'accélération matérielle ou un repli vers le rendu logiciel. C'est normal sous WSLg — WSL2 n'expose pas directement votre GPU Windows au côté Linux, donc la pile GUI bascule vers des chemins logiciels. L'application se lance correctement et s'exécute à pleine vitesse Beadbox ; les avertissements sont du bruit, pas des erreurs.

Contexte et références

Les deux builds (.exe Windows et .deb Linux) proviennent de la même base de code Beadbox. La raison pour laquelle le .exe ne peut pas piloter un workspace WSL est structurelle, pas un bug que nous prévoyons de corriger — les calculs de latence et le pont de système de fichiers jouent contre lui.

Si vous voulez le détail architectural derrière cette décision, les briefs de conception et le tracer de latence qui ont écarté les chemins rejetés sont liés ci-dessous.