Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

WSL2 Ubuntu Setup

While not strictly a requirement, your development workflow might benefit from creating multiple WSL environments instead of using one environment for everything. By having multiple instances, you can cleanly isolate libraries, dependencies etc. and restart from clean state if need.

Installing WSL2 on Windows

This step is only required for Windows users. Linux users can skip this step. Before you continue with the steps below, make sure you have a working WSL 2 installation. For instructions on installing WSL 2 on Windows, follow the instructions on Microsoft’s website.

Next, verify that your WSL 2 installation. Open a Windows terminal or powershell and key in the wsl --version. You should see output similar to the following. Make sure your WSL version is also over 2.

> wsl --version
WSL version: 2.5.7.0
Kernel version: 6.6.87.1-1
WSLg version: 1.0.66
MSRDC version: 1.2.6074
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.26100.7171

PowerCommons Ubuntu WSL Image - Automated Installation

You can use the following script to provision a complete WSL development environment for the PowerCommons project that includes all development dependencies, Litex, FuseSoc, OpenOCD etc.

Note

If you want to find your home directory, run the following in PowerShell: echo $env:USERPROFILE

To use this script, create a folder called .cloud-init in your Windows $HOME folder. Create a file called Ubuntu-24.04.user-data inside this folder and copy paste the following contents in this file:

#cloud-config
locale: en_US
users:
- name: powercommons
  gecos: Power Commons
  groups: [adm,dialout,cdrom,floppy,sudo,audio,dip,video,plugdev,netdev]
  sudo: ALL=(ALL) NOPASSWD:ALL
  shell: /bin/bash

write_files:
- path: /etc/wsl.conf
  append: true
  content: |
    [user]
    default=powercommons

packages: [git, libc6-dev-i386, net-tools, graphviz, make, unzip, zip, g++,
          xvfb,  libnss3-dev, libgdk-pixbuf2.0-dev, libgtk-3-dev,
          libxss-dev, libasound2-dev, openssl, fdisk, libsecret-1-dev, curl, wget,
          build-essential, libssl-dev, zlib1g-dev, libbz2-dev, libreadline-dev, libsqlite3-dev,
          libncurses-dev, xz-utils, tk-dev, libxml2-dev, libxmlsec1-dev, libffi-dev, liblzma-dev, libzstd-dev, tio,
          cmake, ninja-build, ccache, autoconf, automake, libtool, pkg-config,  gcc-powerpc64le-linux-gnu, g++-powerpc64le-linux-gnu, 
          binutils-powerpc64le-linux-gnu, flex, bison, bc, libssl-dev, libelf-dev, device-tree-compiler, qemu-system-ppc64, openocd]

runcmd:
   - sudo apt update && sudo apt -y upgrade
   - sudo git clone https://github.com/Microsoft/vcpkg.git /opt/vcpkg
   - /opt/vcpkg/bootstrap-vcpkg.sh
   - su - powercommons -c 'curl -fsSL https://pyenv.run | bash'
   - su - powercommons -c 'curl -s https://ohmyposh.dev/install.sh | bash -s'
   - su - powercommons -c 'ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519'
   # Write all bashrc entries
   - |
     su - powercommons -c 'cat >> ~/.bashrc << "EOF"
     export PYENV_ROOT="$HOME/.pyenv"
     [[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$HOME/.local/bin:$PATH"
     eval "$(pyenv init - bash)"
     eval "$(pyenv virtualenv-init -)"
     eval "$(oh-my-posh init bash --config ~/.cache/oh-my-posh/themes/atomic.omp.json)"
     EOF'
   # Chain pyenv commands in one shell with explicit env setup
   - |
     su - powercommons -c 'export PYENV_ROOT="$HOME/.pyenv" && \
       export PATH="$PYENV_ROOT/bin:$HOME/.local/bin:$PATH" && \
       eval "$(pyenv init -)" && \
       pyenv install 3.12 && \
       pyenv virtualenv 3.12 microwatt'
   - su - powercommons -c 'mkdir -p projects && cd projects && git clone https://codeberg.org/PowerCommons/microwatt.git'
   # LiteX in activated venv
   - |
     su - powercommons -c 'export PYENV_ROOT="$HOME/.pyenv" && \
       export PATH="$PYENV_ROOT/bin:$HOME/.local/bin:$PATH" && \
       eval "$(pyenv init -)" && \
       eval "$(pyenv virtualenv-init -)" && \
       pyenv activate microwatt && \
       pip3 install --upgrade fusesoc && \
       mkdir -p ~/projects/litex && cd ~/projects/litex && \
       wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py && \
       chmod +x litex_setup.py && \
       ./litex_setup.py --init --install --config=standard'
   - sudo ln -s /usr/lib/x86_64-linux-gnu/libcurses.so /lib64/libncurses.so.6
   - sudo ln -s /usr/lib/x86_64-linux-gnu/libtinfo.so /lib64/libtinfo.so.5

Next, open a Windows Terminal or Powershell and run the following command. Note that the name of the distribution must match the name of the file you created above.

wsl --install -d Ubuntu-24.04 --name PowerCommons

Once the process completes, you will be logged into your new WSL instance.

Note

The cloud-config will:

  1. Create a user named powercommons with the password powercommons and set it as default via /etc/wsl.conf
  2. Create a python virtual environment called microwatt
  3. Install all required packages and dependencies as listed in the packages section of the yml config above.
  4. The script will create a folder called projects in the home folder of the user powercommons, clone microwatt repository, and install Litex with standard distribution.

Feel free to explore the yml configuration script above to understand what is installed and configured.

Creating an Ubuntu WSL 2 Instance - Manual installation

If you want to install and configure your WSL instance manually, you can run wsl --install -d Ubuntu-24.04 --name PowerCommonsA2OISAUpgrade. :

> wsl --install -d Ubuntu-24.04 --name PowerCommonsA2OISAUpgrade
Downloading: Ubuntu 24.04 LTS
Installing: Ubuntu 24.04 LTS
Distribution successfully installed. It can be launched via 'wsl.exe -d PowerCommonsA2OISAUpgrade'
Launching PowerCommonsA2OISAUpgrade...
Provisioning the new WSL instance PowerCommonsA2OISAUpgrade
This might take a while...
Create a default Unix user account: power2people
New password:
Retype new password:
passwd: password updated successfully
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.
power2people@DESKTOP-P4O:/mnt/c/Users/anonymous$

Choose a username and a password when prompted and save it in a password manager - you will need it later. In the example above, we used power2people as the username. Once the process finishes, you will be logged in to the new instance and land at the shello.

This process will also install a shortcut by the name of PowerCommonsA2OISAUpgrade in your start menu in Windows. You can use this shortcut to launch the PowerCommonsA2OISAUpgrade Ubuntu instance later or after a restart.

Note that multiple shells can be opened simultaneously without interfering with each other. Refer to Ubuntu’s WSL documentation for details.

Creating multiple WSL instances

If you are going to be working on multiple projects, it is highly recommended to create multiple WSL 2 instances - one for each project to avoid mixing up libraries and for isolation. To creat a second instance using Ubuntu, just change the --name parameter for you new installation. For instance, you can have three WSL instaces - each dedicated to a specific project:

  • wsl --install -d Ubuntu-24.04 --name A2ORevival : Creates an instance for A2O Revival project.
  • wsl --install -d Ubuntu-24.04 --name A2OISAUpgrade : Creates an instance for A2O Upgrade project.
  • wsl --install -d Ubuntu-24.04 --name Microwatt : Creates an instance for Microwatt project.

Next Steps