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)
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:
Press the Windows button to search for " Turn Windows features on or off"
Windows Subsystem for Linux" and click OK. You will be prompted to reboot.
OPTIONAL: Update to WSL2
For the speed of a real Linux kernel on Windows one can activate WSL2. When activated the speed is comparable to a real Linux distribution ONLY when working in the Linux file system.
To update to WSL2, you have to be running on Windows 10..
For x64 systems: Version 1903 or later, with Build 18362 or later.
For ARM64 systems: Version 2004 or later, with Build 19041 or later.
Enable the Virtual Machine Platform optional feature by opening PowerShell as Administrator (Start menu > PowerShell > right-click > Run as Administrator) and enter the following command.
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart your PC.
Download the latest WSL2 Linux kernel package.
Set WSL2 as your default version by opening PowerShell as Administrator (Start menu > PowerShell > right-click > Run as Administrator) and enter the following command.
wsl --set-default-version 2
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
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
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
Skip this step when working on WSL2
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
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.