Building on Windows/WSL2

Build SerenityOS on Windows using WSL2 (Windows Subsystem for Linux)

SerenityOS can be built and run under WSL Version 2. WSL Version 1 is not supported since it lacks ext2 filesystem support.

Prerequisites

WSL Version 2 requires:

• Windows 10 version 2004 or higher
• OS Build 19041 or greater

Installing WSL2

1. Install WSL2

   Follow the official Microsoft guide: Get WSL2

2. Verify WSL version

   Check your installed distributions and versions:

   wsl -l -v
   
3. Convert to WSL2 (if needed)

   If your distribution is using Version 1, convert it:

   wsl --set-version <distro> 2
   
4. Set default version (optional)

   To make WSL2 the default for all new distributions:

   wsl --set-default-version 2
   

Install Build Dependencies

Once WSL2 is set up, follow the Linux build instructions for your chosen distribution:

Ubuntu/Debian

Most common choice for WSL2

Other Distributions

Arch, Fedora, and more

Filesystem Performance

Critical Performance Note:

WSL2 filesystem performance for IO-heavy tasks (like compiling C++ projects) is significantly slower on the Windows filesystem compared to the Linux filesystem.

Recommended Setup

Store your project in the Linux filesystem:

# Clone to Linux filesystem
cd ~
git clone https://github.com/SerenityOS/serenity.git
cd serenity

Accessing Linux Files from Windows

You can access your Linux filesystem from Windows Explorer at:

\\wsl$\<distro-name>\home\<username>\serenity

For example:

\\wsl$\Ubuntu\home\john\serenity

This allows you to use Windows editors and tools while keeping the build fast.

Setting up QEMU

1. Download QEMU for Windows

   Download the latest QEMU binaries from qemu.org

2. Install required components

   During installation, select at minimum:

   • Tools

   • System emulators (i386 and x86_64)

   • DLL libraries

     
3. Build and run SerenityOS

   Meta/serenity.sh run
   

Hardware Acceleration

By default, QEMU runs in software virtualization mode, which is very slow. Enable hardware acceleration for better performance:

1. Enable Windows Hypervisor Platform

   GUI Method

   1. Open “Turn Windows features on or off”

   2. Check Windows Hypervisor Platform

   3. Click OK

      

   PowerShell Method

   Run in an elevated PowerShell session:

   dism /Online /Enable-Feature /All /FeatureName:HypervisorPlatform
   
2. Reboot

   You may need to reboot after enabling WHPX.

3. Run SerenityOS

   QEMU will automatically use WHPX when available:

   Meta/serenity.sh run
   

Advanced Filesystem Configuration

Using Native Windows Partitions

For better QEMU performance, you can copy the disk image to a native Windows partition:

# Copy disk image to Windows C: drive
cp Build/_disk_image /mnt/c/serenity/_disk_image
cp Build/Kernel/Kernel /mnt/c/serenity/Kernel

Then configure SERENITY_DISK_IMAGE to point to the Windows path (e.g., D:\serenity\_disk_image).

This avoids the 9P network filesystem overhead when accessing WSL2 files from Windows QEMU.

WSL Network Path

The root of your WSL2 distribution is accessible from Windows at:

\\wsl$\{distro-name}

Troubleshooting

WSL Version Issues

If you’re unsure about your WSL version:

# List distributions and versions
wsl -l -v

# Should show VERSION 2

Performance Problems

If builds are very slow:

1. Verify you’re using Linux filesystem (not /mnt/c/)
2. Check current directory:
   pwd
   # Should be /home/<user>/... NOT /mnt/c/...
   

QEMU Launch Failures

If QEMU doesn’t start:

1. Verify QEMU is in Windows PATH
2. Check QEMU installation:
   qemu-system-x86_64 --version
   
3. Ensure hardware acceleration is enabled

File Permission Errors

If you encounter permission issues:

# Fix executable permissions
chmod +x Meta/serenity.sh
chmod +x Toolchain/*.sh

Best Practices

Use Linux filesystem for source code

Always clone and build in /home/ or /root/, never in /mnt/c/ or other Windows mounts.

Enable hardware acceleration

WHPX provides massive performance improvements. Always enable it.

Use Windows editors with WSL files

Access your Linux files via \\wsl$\ to use VS Code, Sublime, or other Windows editors.

Allocate sufficient resources

Configure WSL2 memory and CPU limits in .wslconfig:

[wsl2]
memory=8GB
processors=4

Next Steps

Build System Overview

Learn about the SuperBuild system

Advanced Options

Explore CMake options and customization