Using WSL2 for iverilog, gtkwave & C++
Posted on :: Hardware Verilog

The following blog was written and summarized with the help of Gemini AI.

Windows WSL2 Digital Design & C++ Setup Guide

A complete, modern guide to setting up a high-performance, lightweight Linux development sandbox on Windows using WSL2 (Debian). This guide details the complete configuration for native C/C++ compilation (gcc, g++, make), cross-OS Git synchronization, line-ending normalization, an HDL simulation suite (iverilog, gtkwave).

1. Why WSL2 Debian over MSYS2 or Ubuntu?

When configuring a build environment on Windows, developers typically evaluate three avenues:

  • MSYS2 / MinGW-w64: Runs natively on Windows using the Universal C Runtime (UCRT). While excellent for standalone Windows binaries, it lacks true POSIX compliance, forcing hardware description tools or embedded toolchains to rely on Windows ports that can be brittle or perform poorly.
  • WSL2 Ubuntu: The default choice, but heavily bundled with system background services, Snap packages, and unnecessary telemetry that consumes memory and system overhead.
  • WSL2 Debian: The optimal lightweight solution. Ubuntu is derived from Debian, meaning Debian uses the identical, robust apt package manager. However, Debian starts as a clean slate, using minimal base memory, running no bloated background daemons, and leaving maximum hardware resources available for heavy compiler passes, cross-compilation, and simulation loops.

2. WSL2 Debian Core Installation

If you ran a baseline wsl --install and see no default Linux distributions when running wsl -l -v, follow these steps to deploy a clean Debian environment.

Step 1: Provision the Distribution

Open a PowerShell or Windows Command Prompt with Administrator privileges and check available online distributions:

wsl --list --online

Install the core Debian distribution package:

wsl --install -d Debian

Step 2: Initialize Linux Environment

  1. A new console window will automatically initialize the environment.

  2. Provide a Linux Username and Password when prompted (this establishes your local administrative credentials for sudo).

  3. Verify your running environment version from a fresh PowerShell terminal:

    wsl --list --verbose

    Note: Under the VERSION column, verify that it displays 2. WSL2 uses a real, optimized Linux kernel running within a highly efficient hypervisor.

Understanding Storage Allocations (The 1TB Illusion)

When installing packages, the package manager may print a disk utilization metric similar to:

Space needed: 366 MB / 1,026 GB available

Do not be alarmed if you only have a 256GB or 512GB host SSD. WSL2 provisions virtual environments inside a Dynamically Expanding Virtual Hard Disk (ext4.vhdx). Linux reads the maximum internal boundaries of the volume (capped at 1TB by default), but on your host Windows partition, the file only occupies the exact number of bytes used by your files (typically ~1.5GB to 2.5GB for a base setup). It will never overwrite or affect external physical disk partitions, including native Linux dual-boot setups.

3. Installing C/C++ Build Essentials

Log into your fresh Debian terminal interface and execute a system package registry synchronization followed by a core utility installation.

# Update the local package metadata lists
sudo apt update

# Execute pending security or architectural upgrades
sudo apt upgrade

# Install the consolidated compilation package
sudo apt install build-essential

Verification

Ensure the tools are successfully linked to your runtime PATH by querying their respective versions:

gcc --version
g++ --version
make --version

4. Cross-OS Git & File System Configuration

Running a Windows-native Git executable (git.exe) inside a Linux directory structure introduces performance degradation and cross-system friction. The correct design paradigm is to utilize a native Linux Git instance but securely pipe configurations and permissions.

Step 1: Install Native Linux Git

sudo apt update && sudo apt install git -y

Step 2: Neutralize Shared Partition Permission Errors

When opening an existing repository located on a shared cross-OS partition (e.g., an NTFS or exFAT drive mounted inside WSL under /mnt/), running git diff will often output a catastrophic permission mode shift:

old mode 100644
new mode 100755

This occurs because Windows file systems do not map native Linux execution attributes (chmod +x) natively, making every file look executable to the WSL subsystem. Force Git to ignore file mode changes globally:

git config --global core.fileMode false

Step 3: Absolute Line-Ending Normalization (CRLF vs LF)

Windows environments parse newlines as Carriage Return + Line Feed (), while Linux requires standard Line Feed (). If unmanaged, modifying a file on Windows will corrupt the entire Git change log by flagging every single line as modified.

Configure Git within WSL to use the Input Filter. This translates CRLF to LF instantly on incoming commits, but ensures checking out repositories retains LF:

git config --global core.autocrlf input

Step 4: Credential Sharing & Identity Syncing

If you wish to retain Git on Windows alongside WSL, you can instruct your Linux environment to borrow your Windows secure identity vault so you never re-authenticate:

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

Finally, configure your development signature profile:

git config --global user.name "Your Global Handle"
git config --global user.email "your.email@example.com"

5. Integrating VS Code with WSL

Visual Studio Code provides a split architecture for headless or virtualized development. The user interface runs natively on your Windows desktop GPU, while a background node compiler backend agent executes inside the Debian container environment.

  1. Launch VS Code natively within Windows.

  2. Access the Extension Marketplace (Ctrl + Shift + X).

  3. Install the official WSL Extension published by Microsoft.

  4. To open any project directory, open your WSL Debian terminal, navigate to the targeted project folder, and enter:

    code .

  5. VS Code will load instantly. Look at the lower-left status accent bar; it will explicitly display WSL: Debian, confirming that all terminal instances, linters, and compiler lookups are executing natively through your lightweight Linux layer.

Mandating LF in VS Code

Ensure VS Code forces Line Feed standard natively for any newly generated text assets:

  1. Open global Settings via Ctrl + ,.
  2. Search for the term: eol
  3. Locate the parameter Files: Eol and alter the variable selection from auto to .

6. Hardware Description Language (HDL) Simulation Setup

For digital design and verification engineering workflows, deploy the ultra-fast Icarus Verilog compiler and GTKWave visualization engine inside your Debian workspace.

sudo apt update
sudo apt install iverilog gtkwave

Running GUI Frameworks Natively via WSLg

WSL2 supports native graphical acceleration (WSLg) automatically out of the box. Running the command gtkwave inside Debian will render the complete Linux graphical client application layout window seamlessly right onto your Windows desktop canvas.

Because launching a GUI application blocks input streams inside active CLI terminals, always attach a background processing ampersand (&) flag when invoking graphical entities:

gtkwave design_dump.vcd &

This hands system interactive control back to your shell prompt immediately while the visualization application runs asynchronously in the background.

Table of Contents