Beadbox on Windows + WSL2

왜 WSL에서 Linux Beadbox인가

워크스페이스가 \\wsl.localhost\Ubuntu\home\you\my-project 같은 경로에 있을 때, Windows에서 실행되는 Beadbox.exe는 매번 bd CLI 호출마다 9P 파일 시스템 브리지를 가로질러 접근해야 합니다. bd CLI는 호출마다 Go 런타임을 부트스트랩하고 임베디드 Dolt 저장소를 다시 초기화하며, WSL2 내부의 Linux 커널은 Windows 측이 안정적으로 준수할 수 없는 flock() 의미론을 강제합니다.

결과적으로 두 가지 실패 모드가 발생합니다: 약 1240ms로 측정되는 웜 호출 (Beadbox의 500ms 폴링 임계치를 한참 초과), 그리고 두 프로세스가 동시에 워크스페이스에 접근할 때 간헐적으로 발생하는 flock 오류. 더 깔끔한 해법은 워크스페이스가 이미 있는 곳 — WSL2 안 — 에서 Beadbox를 실행하고, WSLg가 Windows에서 GUI를 렌더링하게 하는 것입니다.

사전 준비

이 가이드는 WSL2 안의 Ubuntu 24.04 LTS를 대상으로 합니다. Ubuntu 22.04에서는 동작하지 않습니다 — Beadbox .deb는 libwebkit2gtk-4.1에 의존하는데, 이 라이브러리는 24.04 이상에서만 기본 제공됩니다. 더 오래된 WSL2 배포판에서는 의존성 미충족 오류로 설치 단계에서 실패합니다.

Step 1 이전에 두 가지 사전 준비가 필요합니다:

1. WSL1이 아니라 WSL2를 기본값으로 설정하세요. WSLg는 WSL2에서만 GUI 앱을 렌더링합니다. 배포판을 설치하기 전에 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.

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 릴리스에서 최신 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가 디스플레이를 협상하는 동안 첫 실행은 몇 초가 걸릴 수 있습니다. 그 후 Beadbox는 다른 네이티브 창처럼 동작합니다: 작업 표시줄에 고정하고, alt-tab으로 전환하고, 모니터를 가로질러 드래그하세요. 워크스페이스를 열 때는 Windows 측 경로가 아니라 Linux 측 경로 (~/my-project)를 가리키세요. WSL 안에서는 ~/가 올바른 홈입니다.

팁: 시작 메뉴 바로 가기를 원한다면, .deb는 Windows가 자동으로 "Beadbox (Ubuntu)" 또는 비슷한 이름으로 표시하는 .desktop 항목을 설치합니다. 설치 후 시작 메뉴에서 검색하세요.

이미 flock 오류를 만났나요?

Beadbox.exe를 설치하고 WSL 워크스페이스를 열려고 시도했다면, flock, 임베디드 모드 실패, 또는 워크스페이스 로드 실패를 언급하는 오류를 보았을 것입니다. 해결책은 간단합니다:

1. Beadbox.exe에서 워크스페이스를 닫거나 (또는 앱을 완전히 종료하세요). 네이티브 Windows 빌드는 이 워크스페이스에서 작동하지 않습니다.
2. Linux Beadbox를 설치하기 위해 WSL2 배포판 안에서 위의 설치 단계를 따르세요.
3. 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 워크스페이스를 구동할 수 없는 이유는 구조적인 것이지 우리가 고칠 계획인 버그가 아닙니다 — 지연 시간 계산과 파일 시스템 브리지가 그것에 불리하게 쌓여 있습니다.

이 결정 뒤에 있는 아키텍처적 세부 사항을 원한다면, 디자인 브리프와 거부된 경로들을 배제한 지연 시간 트레이서가 아래에 링크되어 있습니다.

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