Skip to content
MRS Qt SDK

Set Up the Virtual Machine

The MRS SDK Qt project provides a pre-built Ubuntu 24.04 LTS Desktop virtual machine image with Qt Creator and pre-configured build kits. This guide walks you through obtaining, importing, and using the VM.

Quick Start

Section titled “Quick Start”
  1. Install virtualization software for your host OS
  2. Obtain the VMDK image (download or build locally)
  3. Import it into your virtualization platform
  4. Launch the VM and start developing with Qt Creator

Image Contents

Section titled “Image Contents”

The VM includes:

  • Ubuntu 24.04 LTS Desktop (minimal)
  • Qt Creator IDE
  • Build tools (gcc, g++, make, cmake, ninja, git)
  • MRS Qt SDK pre-cloned at ~/repos/mrs-sdk-qt/
  • Automatic provisioning script:
    • Installs Qt 5.15.0 LTS and Qt 6.8.0 LTS development kits with all modules

Install Virtualization Software

Section titled “Install Virtualization Software”

Here are our recommended platforms depending on your host operating system:

Host OSVirtualization
WindowsVirtualBox, VMWare
Linuxvirt-manager

Obtain the VM Image

Section titled “Obtain the VM Image”

Option 1: Download Pre-built Image

Section titled “Option 1: Download Pre-built Image”

Pre-built VM images are available for download:

  1. Visit the MRS SDK Qt VM Images OneDrive folder
  2. Download the latest mrs-sdk-qt.vmdk file
  3. Follow the import instructions below

Option 2: Build Locally

Section titled “Option 2: Build Locally”

To build the VM image on your machine:

Prerequisites:

  • Docker with Docker Compose
  • KVM access (optional but recommended for faster builds) /_ The VM disk by default is 60GB. The 80GB number has a safe buffer. _/
  • 80GB free disk space
  • 6+ GB available RAM

Build steps:

Terminal window
cd vm && ./build-vm.sh

The VMDK file will be created in the vm/output/ directory.

More information is available in the VM builder reference.

Import the VM

Section titled “Import the VM”

Import the VMDK file using your virtualization platform (VirtualBox, VMware, etc.):

  1. Open your virtualization software
  2. Import the mrs-sdk-qt.vmdk file
  3. Configure settings (recommended: 6GB RAM, 2 CPUs, 60GB disk)
  4. Start the VM

First Boot

Section titled “First Boot”

  1. Log in with the default user credentials

    • Username: ubuntu
    • Password: ubuntu

  2. Security recommendation: change the password on first login:

    Terminal window
    passwd

  3. Run the provisioning script to install all necessary Qt toolchains:

    Terminal window
    ~/provision.sh

Using the VM

Section titled “Using the VM”

The MRS SDK Qt repository is pre-cloned at ~/repos/mrs-sdk-qt/. You can start developing immediately without needing to clone it.

Starting Qt Creator

Section titled “Starting Qt Creator”

Select Qt Creator from the application menu or open a terminal and run:

Terminal window
qtcreator &

Creating a New Project

Section titled “Creating a New Project”
  1. Launch Qt Creator
  2. File > New Project > Select your desired project type
  3. Qt Creator will display available build kits
  4. Choose your target kit and proceed

Included Build Kits

Section titled “Included Build Kits”
  • Desktop Qt 5
  • Desktop Qt 6

System Tools

Section titled “System Tools”

The VM includes common development tools:

  • GCC compiler and build-essential toolkit
  • CMake and Ninja build systems
  • Git version control
  • SSH client/server
  • Curl and wget

Customization

Section titled “Customization”

Increasing VM Resources

Section titled “Increasing VM Resources”

If you need more processing power:

  1. Stop the VM
  2. In your virtualization platform’s settings:
    • Increase allocated RAM
    • Increase CPU cores
    • Increase disk size (may require filesystem expansion)
  3. Restart the VM

Installing Additional Software

Section titled “Installing Additional Software”

Use the standard Ubuntu package manager:

Terminal window
sudo apt-get update
sudo apt-get install <package-name>

Snapshots and Backups

Section titled “Snapshots and Backups”

Create VM snapshots before making significant changes using your virtualization platform’s snapshot feature.

Troubleshooting

Section titled “Troubleshooting”

Qt Creator Won’t Start

Section titled “Qt Creator Won’t Start”

  1. Verify installation:

    Terminal window
    which qtcreator

  2. Try launching with verbose output:

    Terminal window
    qtcreator -d

  3. Check system logs:

    Terminal window
    journalctl -e

Slow Performance

Section titled “Slow Performance”
  • Ensure VM has adequate RAM allocated (6GB recommended)
  • Check host system resource availability
  • Disable 3D acceleration if causing issues

Network Issues

Section titled “Network Issues”
  • Verify networking is enabled in VM settings
  • Check network adapter status: ip link show
  • Test connectivity: ping google.com

Low Disk Space

Section titled “Low Disk Space”

Check available space:

Terminal window
df -h

If running low, you can clean up apt cache:

Terminal window
sudo apt-get clean
sudo apt-get autoclean

Known Issues

Section titled “Known Issues”
GNOME Boxes

RTC Configuration

Section titled “RTC Configuration”

Boxes is optimized for Windows VMs, which expect the RTC (Real Time Clock) from the host to use the local time, not the UTC time. However, Ubuntu/Linux VMs typically need the RTC to be in UTC time. This is not configurable from the VM; it is determined by the hypervisor software before the VM even boots.

The MRS SDK VM is configured to sync its hardware clock with the host’s UTC clock. So, with the default configuration, the VM will have an incorrect system time, which can cause issues with:

  • Package manager operations (apt)
  • SSL/TLS certificate validation
  • Build timestamps and caching

To enable proper RTC in Boxes, you must edit the VM’s libvirt configuration:

  1. Right-click the VM in GNOME Boxes > Preferences > Resources tab

  2. Click Edit Configuration (bottom of the dialog)

  3. Locate the <clock> tag and modify it to look like this:

    <clock offset="utc">
    ...
    </clock>

  4. Click Save to apply the changes.

  5. Restart the VM. After reboot, the system time will automatically sync with your host system’s UTC clock.

Operating System Auto-Detection

Section titled “Operating System Auto-Detection”

When you go through the process of creating a new VM in GNOME Boxes, you will be presented with a screen like this:

GNOME Boxes setup dialog

The Operating System selector is intended to streamline the process of configuring a new VM. However, the Ubuntu configurations in Boxes have been found to apply certain settings that will break network connectivity in the MRS SDK VM.

So, DO NOT select an operating system or allow auto-detection; leave the input as “not found”.

”Failed to Start” Error

Section titled “”Failed to Start” Error”

Gnome Boxes will often show an error “Failed to start…”, but this can be safely ignored. Wait a few minutes and the VM will start without issues.

Getting Help

Section titled “Getting Help”