Beadbox на Windows + WSL2

Почему Linux-версия Beadbox в WSL

Когда ваш воркспейс находится по пути вроде \\wsl.localhost\Ubuntu\home\you\my-project, Beadbox.exe, работающий в Windows, вынужден обращаться через мост файловой системы 9P при каждом вызове bd CLI. bd CLI инициализирует Go-рантайм и переинициализирует встроенное хранилище Dolt при каждом вызове, а ядро Linux внутри WSL2 обеспечивает семантику flock(), которую сторона Windows не может надёжно соблюдать.

В результате возникают два режима отказа: «прогретые» вызовы, занимающие около 1240 мс (значительно превышая 500-миллисекундный интервал опроса Beadbox), и периодические ошибки flock, когда два процесса одновременно обращаются к воркспейсу. Более чистое решение — запускать Beadbox там, где уже находится воркспейс, то есть внутри WSL2, и позволить WSLg отрисовывать GUI на Windows.

Предварительные требования

Это руководство ориентировано на Ubuntu 24.04 LTS внутри WSL2. Ubuntu 22.04 работать не будет — .deb-пакет Beadbox зависит от libwebkit2gtk-4.1, который нативно поставляется только в 24.04 и более новых версиях. На более старых дистрибутивах WSL2 шаг установки завершится ошибкой о неудовлетворённой зависимости.

Перед шагом 1 нужно выполнить два предварительных условия:

1. По умолчанию используйте WSL2, а не WSL1. WSLg отрисовывает GUI-приложения только на WSL2. Выполните это один раз в PowerShell перед установкой дистрибутива:

   wsl --set-default-version 2

2. Установите Ubuntu 24.04 (или обновите существующий дистрибутив). Этот шаг интерактивный — загрузка образа занимает несколько минут, а по её завершении вам будет предложено создать имя пользователя и пароль Linux:

   wsl --install Ubuntu-24.04

3. Убедитесь, что дистрибутив работает на WSL2:

   wsl --list --verbose

В выводе рядом с Ubuntu-24.04 должно отображаться VERSION 2. Если показывается 1, переведите его: wsl --set-version Ubuntu-24.04 2.

Установка Linux Beadbox в WSL2

Эти команды выполняются в терминале вашего Ubuntu 24.04 WSL2. Откройте его командой wsl -d Ubuntu-24.04 из PowerShell или выберите дистрибутив в выпадающем меню 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. Скачать .deb-пакет Beadbox

Скачайте последний .deb для Linux со страницы релизов на 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. Установить .deb

Сначала обновите индекс apt — свежие дистрибутивы WSL2 поставляются с устаревшим списком пакетов, иначе установка завершится ошибкой 404 на транзитивных зависимостях. Затем установите .deb в той же команде:

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

Если apt по-прежнему сообщает о недостающих зависимостях после обновления, выполните sudo apt --fix-broken install и попробуйте снова.

Запуск через WSLg

WSLg поставляется вместе с WSL2 на Windows 10 и 11 и отрисовывает Linux GUI-приложения прямо на рабочем столе Windows. Никакой настройки X server, никакой дополнительной конфигурации — просто запустите приложение:

beadbox

Первый запуск может занять несколько секунд, пока WSLg согласовывает дисплей. После этого Beadbox ведёт себя как любое другое нативное окно: закрепляйте его на панели задач, переключайтесь на него по alt-tab, перетаскивайте между мониторами. Когда вы открываете воркспейс, указывайте путь со стороны Linux (~/my-project), а не со стороны Windows. Внутри WSL ~/ — это правильный домашний каталог.

Совет: если вам нужен ярлык в меню «Пуск», .deb устанавливает запись .desktop, которую Windows автоматически отображает как «Beadbox (Ubuntu)» или подобное. Найдите её в меню «Пуск» после установки.

Уже столкнулись с ошибкой flock?

Если вы установили Beadbox.exe и попытались открыть воркспейс в WSL, скорее всего, вы увидели ошибку, упоминающую flock, сбой встроенного режима или невозможность загрузить воркспейс. Решение простое:

1. Закройте воркспейс в Beadbox.exe (или полностью завершите приложение). Нативная сборка для Windows не будет работать с этим воркспейсом.
2. Выполните шаги установки выше внутри вашего дистрибутива WSL2, чтобы установить Linux-версию Beadbox.
3. Откройте Beadbox изнутри WSL (выполните beadbox в терминале WSL) и откройте воркспейс по его пути в Linux (~/my-project).

Вы можете оставить Beadbox.exe установленным для проектов, расположенных на стороне Windows (пути вроде C:\Users\you\my-project). Сборка для Windows для них подходит — Linux-сборка нужна только для проектов, размещённых в WSL.

Устранение неполадок

Предупреждения libEGL / Mesa при запуске

При первом запуске beadbox в терминале могут появиться предупреждения от libEGL, Mesa или GL-драйверов об отсутствии аппаратного ускорения или переключении на программный рендеринг. Это нормально для WSLg — WSL2 не предоставляет ваш Windows GPU напрямую Linux-стороне, поэтому графический стек переходит на программные пути. Приложение запускается без проблем и работает с полной скоростью Beadbox; эти предупреждения — шум, а не ошибки.

Контекст и ссылки

Обе сборки (Windows .exe и Linux .deb) собираются из одной и той же кодовой базы Beadbox. Причина, по которой .exe не может работать с воркспейсом WSL, носит структурный характер — это не баг, который мы планируем исправить. Расчёт задержек и мост файловой системы работают против такой схемы.

Если вам нужны архитектурные подробности этого решения, проектные документы и трассировщик задержек, исключивший отвергнутые варианты, приведены ниже.

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