WINDOWS 10 (WSL)

Note: Windows 10 features a bash shell that can run linux software directly on Windows. This makes the installation of MercuryDPM much easier, as it no longer requires the use of an emulator  (like cygwin) or a manual virtual machine.

Two different features have to be differentiated: A Linux kernel emulation for Windows (WSL) and a real Linux kernel running on a virtual machine (Virutal Machine Platform) on Windows (WSL2). Best practice for WSL and WSL2 is sometimes different and therefore alternative steps are highlighted for WSL2. 

Step 1: Activate the Windows Subsystem for Linux (WSL)

1. Open PowerShell as Administrator (Start menu > PowerShell > right-click > Run as Administrator) and enter the following command.

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

If not successful follow the manual activation:

1. Press the Windows button to search for " Turn Windows features on or off"

2. Windows Subsystem for Linux" and click OK. You will be prompted to reboot.

3. Open "Microsoft Store" and install your Linux distribution of choice (e.g. Ubuntu 20.04).  Then click "Open" to open the terminal.

4. Wait for the installation to finish. It will ask you to choose a username and passsword. This password is needed for executing sudo (i.e., administrator) commands, so make sure to remember it.

5. To update the list of repositories from which software can be downloaded and upgrade them, execute the following command. 

sudo apt update && sudo apt upgrade

6. Execute the following command to define the DISPLAY variable (needed for xballs visualisation). Then close the console.

echo "export DISPLAY=localhost:0.0" >> ~/.bashrc

For WSL2  the following command is more suitable to define the display variable.

export DISPLAY=$(ip route|awk '/^default/{print $3}'):0.0

   Note that this has to be repeated after every reboot since the IP of the WSL2 system changes every time you restart your System.

7. Now close the terminal. You can restart it by pressing the Windows button and searching for Ubuntu:

Tip: You can paste each command into the command window by right-clicking the title bar or simply right-clicking on the window:

Step 2: Install X11

1. For visualisation, an X11 server is needed. We recommend the Xming X server. Download that program at https://sourceforge.net/projects/xming, and follow the default installation instructions

2. Open "Xming" from the start menu. There should now be a "X" logo in the notification bar at the bottom left corner of your screen. Mouseover to see the address of the X11 display. (default case 0.0)

Please note: Before using xballs or cmake-gui, make sure you have the Xming X11 server running (step 2, item 2) and the DISPLAY variable set properly (step 6), otherwise the visualisation will NOT work.

Step 3: Change your linux home directory such that it is easily accessible from Windows

1. Skip this step when working on WSL2

2. By default, the Ubuntu shell creates a home directory in the AppData folder in your user directory. This folder is hidden and very hard to access in Windows. We therefore recommend you to use a folder within the Windows file system instead. To do so, create a new folder "C:\dev" on your C-drive, and make bash enter this folder at start-up.

mkdir /mnt/c/dev

cd /mnt/c/dev

echo "cd /mnt/c/dev" >> ~/.bashrc

3.  Add this folder to your Quick Access toolbar:

Step 4: Install MercuryDPM

Now open the bash and follow the installation instructions for Linux to install MercuryDPM.