Development Setup with WSL (Windows Subsystem for Linux)

2. Development Setup with WSL (Windows Subsystem for Linux)#

This guide details how to leverage Windows Subsystem for Linux (WSL 2) to create a Maeser development environment on a Windows machine. By following these steps, you’ll install and configure WSL, set up your Linux distribution (Ubuntu), install essential development tools, and run Maeser within WSL.

2.1. Introduction to WSL#

The Windows Subsystem for Linux (WSL) is a compatibility layer that allows you to run a GNU/Linux environment natively on Windows without the overhead of a virtual machine or dual-boot setup. WSL 2 uses a real Linux kernel, offering near-native performance and full system-call compatibility (en.wikipedia.org).

Why use WSL for Maeser development?

  • Unified Environment: Use Linux-based tooling (bash, Python, make) directly on Windows.

  • Integration: Access Windows files from Linux and vice versa, and use VS Code’s WSL extension for a seamless IDE experience.

2.2. Install & Enable WSL#

  1. Open PowerShell as Administrator.

  2. Run the following command to install WSL 2 and the default Ubuntu distribution:

    wsl --install

    This single command enables required features, downloads the Linux kernel, and installs Ubuntu (learn.microsoft.com).

  3. Restart your machine when prompted.

  4. On reboot, complete the Ubuntu setup by opening Ubuntu (via the Windows Start Menu) and creating your Linux user account and password.

Tip: To install a specific distribution (e.g., Debian), use:

wsl --install -d Debian

2.3. Update & Upgrade Your Linux Distro#

  1. Open Ubuntu (WSL) from the Start menu.

  2. Update package lists and upgrade installed packages:

    sudo apt update && sudo apt upgrade -y

  3. Install essential build tools:

    sudo apt install -y build-essential git curl python3.10 python3.10-venv python3-pip make

2.4. Configure WSL Settings (Optional)#

Create a .wslconfig file in your Windows user directory (e.g., C:\Users\You) to customize WSL 2 VM resources:

[wsl2]
memory=4GB   # Limits VM to 4 GB RAM
#processors=2 # Uncomment to limit to 2 CPU cores
swap=0       # Disable swap (optional)

This file is automatically applied on WSL restarts (en.wikipedia.org).

2.5. Clone & Set Up Maeser in WSL#

Once WSL is set up on your machine, the process for setting up Maeser is identical to setting up the project for Linux. Follow the instructions for Linux users at Development Setup to get Maeser up and running. Make sure to do this in your Ubuntu shell (or equivalent WSL Distribution), not in Powershell.

2.6. Using VS Code with WSL#

  1. Install the VS Code WSL Extension.

  2. Open an Ubuntu shell, navigate to the project folder, and run the following command:

    code .

  3. VS Code now uses the Linux toolchain inside WSL for linting, debugging, and terminal commands.

2.7. Accessing Windows Files#

Windows drives are mounted under /mnt, e.g., your C: drive at /mnt/c. In general, however, you should create and manage Linux projects within the WSL file system (e.g. in ~/projects/...) for best file I/O performance and system permissions.

2.8. Additional Resources#

Contents