simulation/docs/wsl_setup_guide.md

WSL Setup Guide

Setup guide for Windows Subsystem for Linux (WSL2).

Prerequisites

• Windows 10 (version 21H2+) or Windows 11
• WSL2 with Ubuntu 22.04

Install WSL2

Open PowerShell as Administrator:

wsl --install -d Ubuntu-22.04

Restart your computer, then open Ubuntu from the Start menu.

GUI Support

Windows 11 (WSLg)

GUI works automatically. No additional setup needed.

Windows 10 (VcXsrv)

1. Download and install VcXsrv
2. Run XLaunch with these settings:
   • Multiple windows
   • Start no client
   • Disable access control (checked)
3. In WSL, set DISPLAY:

export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

Installation

git clone https://git.sirblob.co/SirBlob/simulation.git
cd simulation
bash setup.sh

The setup script automatically:

• Detects WSL environment
• Installs GUI support packages
• Creates WSL environment file
• Configures DISPLAY variable

Running the Simulation

cd ~/simulation
source activate_venv.sh
bash scripts/run_simulation.sh

If graphics are slow or Gazebo crashes:

bash scripts/run_simulation.sh --software-render

Troubleshooting

Black screen or no display

Check DISPLAY variable:

echo $DISPLAY

For WSLg (Windows 11), should be :0 For VcXsrv (Windows 10), should be <IP>:0

Test with:

xcalc

Gazebo crashes immediately

Use software rendering:

export LIBGL_ALWAYS_SOFTWARE=1
bash scripts/run_simulation.sh

OpenGL errors

export MESA_GL_VERSION_OVERRIDE=3.3
export MESA_GLSL_VERSION_OVERRIDE=330

VcXsrv connection refused

1. Check Windows Firewall allows VcXsrv
2. Ensure XLaunch is running
3. Disable access control in XLaunch settings

Slow performance

• Close unnecessary Windows applications
• Allocate more RAM to WSL in .wslconfig:

[wsl2]
memory=8GB
processors=4

• Use software rendering flag

Environment Variables

The activate_venv.sh script sets these automatically:

export DISPLAY=:0  # or IP:0 for VcXsrv
export LIBGL_ALWAYS_INDIRECT=0
export MESA_GL_VERSION_OVERRIDE=3.3

Uninstall

bash scripts/uninstall.sh --all