WSL

WSL#

Windows Subsystem for Linux (WSL) is a lightweight virtual machine alternative for Windows 10 that allows us to build and debug POLARIS on Linux without having to clone the repository to another directory.

WSL is easier to configure at Argonne, but you can install POLARIS on a virtual machine or any other Linux installation. We will use Ubuntu here as it is the easiest and most common distro.

Installing WSL#

Full instructions here: https://docs.microsoft.com/en-us/windows/wsl/install-win10

Make sure your Windows system meets the minimum requirements:

For x64 systems: Version 1903 or higher, with Build 18362 or higher.
For ARM64 systems: Version 2004 or higher, with Build 19041 or higher. To check your version and build number, select Windows logo key + R, type winver, select OK.

Before installing the WSL program itself, we need to configure windows to use it:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

You should restart at this point.

Next, download and install the Linux kernel update package for windows: https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi

Set WSL2 as your default version:

wsl --set-default-version 2

Finally, install from the Image file in our Box drive or from scratch with the linux distribution of your choice (Ubuntu 20.04 recommended). The easiest way to do this is to search for “Microsoft Store” in the Windows 10 help bar and search for the distribution you want. The full instructions above have direct links to available distributions.

Installing Build Tools#

For Ubuntu, run the following commands to install everything:

sudo apt update
sudo apt install -y build-essential gcc-10 g++-10 cmake ninja-build git-all gcc-10-plugin-dev python3 python3-dev python3-pip patchelf pigz patchelf pigz

In Ubuntu 20.04 the default gcc is 9.4, but we want to use 10.3 as our default:

sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 10
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 10
sudo update-alternatives --set gcc /usr/bin/gcc-10
sudo update-alternatives --set g++ /usr/bin/g++-10

Editing Code#

Once you have cloned the repo and built it using python build.py -cb you might be wondering, great - now how do I edit these files?

The easiest way to edit files that live on your WSL filesystem is to use the VS Code IDE with the WSL Extension. After installing the extension, you should be able to open a new WSL session by pressing Ctrl-Shift-P, typing wsl and then selecting “WSL: Open Folder in WSL” which will let you select the folder location where you cloned POLARIS and will then give you a full IDE experience (including built in terminal [`Ctrl+``]) as if you were running inside of the WSL instance.

Optional Setup#

Windows Terminal for WSL#

It is highly recommended to download Windows Terminal from the Windows Store instead of using the built in Ubuntu prompt. The Windows Terminal is signficantly more functional and will allow you to use multiple tabs with different command prompts (WSL and cmd.exe/PowerShell command prompts next to each other, multiple tabs for each, etc.)

Connect Network Drives to WSL#

If you have network drives from Windows that you want to access through WSL, you can connect them in two ways. We will use the P: drive as an example:

mkdir /mnt/p
mount -t drvfs P: /mnt/p

The above mounts the drive temporarily, until you exit WSL or log off. To make the change permanent, you need to open /etc/fstab (ex. “nano /etc/fstab” will open this file for editing) and add the following line:

P: /mnt/p drvfs defaults 0 0

Then, reload the fstabs file by entering this line:

sudo mount -a

You also do not need to have the network drive mounted in windows to mount it in WSL. The following is a commonly used set of network mounts for WSL based images which provides consistent easy access to commonly used network locations.

\\VMS-FS.es.anl.gov\VMS                            /mnt/p drvfs defaults 0 0
\\VMS-FS.es.anl.gov\VMS_Studies                    /mnt/q drvfs defaults 0 0

Change Starting Directory in WSL#

To make things easier, we will make it so Ubuntu opens into your Polaris directory every time it is started. Call the following:

cd ~
sudo nano .bashrc

nano is a text editor, and unfortunately probably the easiest to use from command line. You can move around with the arrow keys and type normally. At the bottom of the file, add the following (use the actual directory that your Polaris files are in):

cd /mnt/c/%Your-Polaris-Directory%

Then use Shift+X to exit. It will ask you to save, press y; it will ask you the name to save under, just press enter to keep the name the same.

If you want to find this file in Windows File Explorer and edit with a standard text editor, navigate to your WSL drive and find /home/%USER%/.bashrc: https://www.howtogeek.com/426749/how-to-access-your-linux-wsl-files-in-windows-10/

Editing with QtCreator#

The Linux version of Polaris does not have debug symbols at the moment, so this is not strictly necessary - you can find errors with build-polaris.sh and fix them in Visual Studio.

WSL does not have a graphical element, so we need to create a graphical server in windows. The instructions here worked for me: https://virtualizationreview.com/articles/2017/02/08/graphical-programs-on-windows-subsystem-on-linux.aspx

My preferred editor is qtcreator: https://www.osradar.com/install-qtcreator-on-ubuntu-20-04-18-04/

If you get an error “error while loading shared libraries: libQt5Core.so.5” you may need to run this command:

sudo strip --remove-section=.note.ABI-tag /usr/lib/x86_64-linux-gnu/libQt5Core.so.5

To open Polaris in QtCreator, enter “sudo qtcreator” in the command line. Then Open the CMakeLists.txt file at the top of your Polaris directory and let it configure the files - you should be able to build and debug now.

WSL

Contents