Debugging-with-a-VM.md

title	toc
Debugging with a virtual machine and Linux	true

Sometimes a problem can be reproduced only on a user's machine. Since most GemRB developers are not using Windows, it's hard to provide good instructions to try to find out what's at fault. One option presents itself as solving several obstacles — building GemRB manually on a Linux virtual machine. That way the environment is predictable, known and all the usual developer tools and tricks are available.

This page is a guide on how to set everything up. By the end of it you will be running Linux on your Windows system without one affecting the other.

What is a virtual machine?

A virtual machine (VM) allows you to run one operating system inside a sandbox in another system. A machine inside another. A host is your operating system (probably Windows), a guest is the system that is running inside the virtual machine.

The virtual machine in this guide is VirtualBox, a free software project as well. In the last two sections, you can find brief instructions also for VMWare and WSL2.

It's easy to set up, but it doesn't work if you have turned on Hyper-V on your Windows machine. If you don't know what that is — good, then it's most likely not on.

A few general Linux notes

If you picked Kubuntu (KDE) your virtual machine will be slightly similar to Windows. You'll have a start menu where you can find all your programs, default programs like Mozilla Firefox, a text editor, a file browser etc. Some things are quite different, though:

• Linux is case sensitive. GemRB, gemrb and Gemrb would all be different files.
• Linux uses forward slash instead of backwards slash for file paths.
• Linux doesn't have drive letters (no C:\). Drives are available under /media.
• Your main directory for user files is "home" which is found under /home/YourUserName or ~ for short.
• sudo is used to run something with admin privileges. It's needed to install things system-wide.
• To navigate in the terminal, the main command is cd to change directory. cd .. moves one level up. cd ~ will bring you back to your home directory. Also, if you have file paths with spaces or apostrophes in them, to use them in the terminal you'll need to escape them like so ~/Baldur's\ Gate\ 2 or "~/Baldur's Gate 2".
• You can copy from and paste into the terminal, but not with Ctrl-C and Ctrl-V. Ctrl-C terminates the currently running program. Instead, use Ctrl-Shift-C and Ctrl-Shift-V.
• To install software, you don't download files manually, but let the package manager do that for you (apt on Kubuntu).

Setting up a Linux VM with VirtualBox

• First download VirtualBox from this page, select the one for Windows hosts.
• Install Virtual Box, reboot if prompted.
• Get Kubuntu, a so called Linux distribution, representing a full system. Download the latest LTS (Long Term Support) release ISO file.
• Create a new virtual machine.
  • Give it a name
  • Select Type Linux and Version Ubuntu (64 bit)
  • Allocate it a good bit of memory, RAM (depending on the RAM your system has, it shouldn't be more than half of that, 4-8 GB is enough)
  • Keep the settings for virtual hard disks at default, but change the size. If you just want to debug one or two unmodded games, 25GB should be enough. If you plan to install any huge mods or debug more games, you'll probably want to give that virtual drive 100GB+.
  • Once the setup wizard has finished, open settings again and go to the Display tab. Max out the Video Memory slider to 128MB.
• Now it's time to start the virtual machine. It will ask you for a file, select the ISO you just downloaded. It will take a moment, then the installer will start. Select "install" instead of "try", enter your preferred settings for keyboard, names and passwords and when asked, select "erase disk". Don't worry, this is just your virtual disk, no the real one.
• After it's done installing, it will ask you to reboot. Agree, then when it asks you to remove the installation medium, go to Devices > Optical Drives > Remove disk from virtual drive. Your virtual machine will now reboot.

Making your existing files visible to the virtual machine

• Open a terminal ("Konsole") and install dependencies for guest additions:

sudo apt install virtualbox-guest-additions-iso

• When it's done, in the VirtualBox menu, select Devices > Insert Guest Additions CD Image.
• Follow the popup suggestion and open it in your file manager.
• Double click autorun.sh to run it and enter your password.
• Guest additions allows you to:
  • Share your clipboard with the guest (enable under Devices > Shared Clipboard)
  • Share a folder on your host's drive with the guest
  • Arbitrary resize windows for the guest
• Enter sudo usermod -a -G vboxsf $USER, this will add your current user to the vboxsf group, allowing you to access the shared folder in the next step.
• Turn off the virtual machine.
• To add a shared folder, we open the VM's settings again. Shared Folders > Click the green plus icon > Select a folder you want to share, click auto-mount. Everything you place in this folder can be seen and used by both, the host and the guest.
  • For easier access, you can set a mount point. A good one would be in your home directory, for example ~/VirtualBox
  • You should only use this to give the VM access to a single, isolated, shared folder. Don't give it access to C:\ or all your Documents and games or anything like that. You can edit and break things inside the shared folder from inside your VM.
• Boot into your VM. The folder should appear now. You can put your game installation in there, access it from your VM and move it into your VM.

Installing GemRB and the debugger

• Open a terminal ("Konsole").
• Install the dependencies needed to build GemRB. Remember you can just copy and paste commands.

sudo apt install git cmake make clang libsdl2-2.0-0 \
  libsdl2-dev libopenal1 libopenal-dev libpython3-dev gdb

• Grab the GemRB code and prepare directories for building (a gemrb folder will appear in your home):

git clone https://github.com/gemrb/gemrb ~/gemrb
cd ~/gemrb
mkdir build
cd build

• Build GemRB

cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j2

• Copy the example settings file into "GemRB.cfg" and automatically fix some settings:

cp ../gemrb/GemRB.cfg.noinstall.sample GemRB.cfg
sed -i 's,GameType=test,GameType=auto,' GemRB.cfg
sed -i 's,^#CaseSensitive,CaseSensitive,' GemRB.cfg

• Open the file by clicking on it in Dolphin, the file manager. Find and set GamePath to point to where you copied or mounted the game data (eg. ~/bg2)
  • Check the docs if you're curious about other settings

Running GemRB in the debugger

• Open a terminal
• If you're not already in the build dir: cd ~/gemrb/build
• Run it with

../admin/run.gdb GemRB.cfg

• While the game is running, you'll have the terminal in the background. If the game crashes at any point, switch to the terminal and you'll see some message that the game crashed. Enter bt to get a backtrace. You can copy that out of the terminal with Ctrl-Shift-C. There are other commands that the devs might ask you to enter into that window, that can give them more information.
• When you are ready to terminate the crashed game, enter q in the debugger window and confirm that you want to close the process, or r to restart the engine.

Updating to the latest code

The developers might ask you to test a fix, so you'll need to get the latest code. This doesn't mean you have to go through the whole process again though! As usual open a terminal and run:

cd ~/gemrb/build
git pull
make -j2

You can ignore warnings from git.

Virtual Box alternatives for advanced users

VMWare

VMWare is another popular virtual machine project. It is a little more complicated to set up, but still follows the same basic process. You will just need to follow the documentation that comes with VMWare a lot more closely to get it going.

You are going to want Workstation Player, the free version of VMWare. You will also need VMWare Tools for passthrough. Scroll down the list here: https://my.vmware.com/en/web/vmware/downloads/#all_products

There is a lot more to tweak and a lot more instructions to set VMWare up, but it is well documented.    Tips: 

• Make sure to set your VM space as big as you will need during the initial setup because you will break all of your fake partitions if you try to expand it after the VM is set up.
• Copy from inside the VM terminal and not from the host. Your hard drive will be inside /mnt/ and copying from inside is much faster than copying from without.
• Remember to install your VMTools plugin. It will have its own setup process that will not be as easy to set up and it will need to be set up from within the Workstation Player.

WSL2

The third option is interesting for Windows 10 users and has built-in GUI support. It's a small linux system embedded within Windows. Setting this up can still be tricky because it will require changing BIOS settings. Most modern chipset have Virtualization technology built in, but do not have it enabled.

Restart Windows and hammer the F10 (or F2, or whatever key opens your BIOS). key while your PC posts. You may need to turn off fast boot in Windows to get into your BIOS.

1. Go to Control Panel.
2. Select "Power Options".
3. Click "Choose what the power buttons do".
4. Click "Change settings that are currently unavailable". (Yes, that’s a real setting.)
5. Uncheck "Turn On Fast Startup" and click Save.

Navigating your BIOS can be tricky, so caution is advised. You will need to search through your BIOS options for something about Virtualization or VT. On some systems it's under "Security". Enable it, save changes and reboot.

You will need to head back into the Control Panel after your system reboots.

1. Select "Programs and Features".
2. Select "Turn Windows features on or off".
3. Make sure Hyper-V is unchecked. This will only allow you to install Windows-based virtual machines and will block WSL. (Same reason for your Virtual Box or VMWare not being unable to create an Ubuntu VM with no particular error.)
4. Scroll down and check the boxes for "Virtual Machine Platform", "Windows Hypervisor Platform", and "Windows Powershell" and click OK.
5. Now open Windows Powershell elevated. Type: dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all
6. This will take a moment. When it is through, you will be prompted to reboot. Do so.
7. Go back into an elevated Windows Powershell. Type: wsl --set-default-version 2
8. The upgrade should happen quickly. Now, this will make our Linux friends really grind their teeth, but open the Microsoft Store. Search for "Ubuntu" and click "Install" when it comes up.

The installation will only take a few minutes, but you will have an Ubuntu Start Menu icon. Click it and VOY-LAH! Up pops an Ubuntu terminal natively in Windows that will run GUI software, including GemRB. You will be able to find your drives under /media/.