Table of Contents:
The recommended virtual machine platform for the AMD64 Apertis system images is VirtualBox. It is typical for the Apertis SDK to be run in a virtual machine, though other image types can also be used. This enables development to be performed on computers running Windows, Mac OS, or different Linux distributions.
You will need a PC with the following configuration to install and run the SDK:
- Dual core CPU at 2GHz or higher
- 8 GB RAM or more
- 12 GB or more free space on the hard disk
If your PC supports Virtualization Technology, make sure that it is enabled. If problems are seen when booting the SDK image, check if Virtualization Technology is enabled in BIOS settings.
- Windows OS
- Oracle VirtualBox. See supported version and installation instructions below.
VirtualBox supported version
While you can use VirtualBox in other environments, and even use other virtualization solutions, the supported setup is to run VirtualBox on Microsoft Windows.
The following table contains the supported version of VirtualBox and VirtualBox Guest additions for each release of Apertis:
|Apertis release||VirtualBox version||VirtualBox Guest Additions version|
|v2020||6.1.12 r139181 (Qt5.6.2)||6.1.12|
|v2021||6.1.12 r139181 (Qt5.6.2)||6.1.12|
|v2022||6.1.12 r139181 (Qt5.6.2)||6.1.12|
If you have not yet installed Oracle VM VirtualBox, to install the current version of this software, please follow these steps:
Download the required version of the VirtualBox installation file for your host platform. Check the table of supported versions above to determine which version of VirtualBox is supported for the Apertis Release you want to use.
Follow the installation procedure provided in the VirtualBox installation guide for your host plaform.
For instructions on uninstalling VirtualBox, are also provided in the user manual.
If you have not already downloaded an Apertis SDK image, the images page contains information regarding the options available. SDK images provided explicitly for use with VirtualBox can be found in two different formats:
- VirtualBox appliance image, file extension
.ova. Since Apertis release version
- Compressed disk image, file extension
Depending on the downloaded image, VirtualBox can be configured as follows:
- Option A: VirtualBox GUI using
- Option B: From the Command Line using
- Option C: VirtualBox GUI using
- Option D: From the Command Line using
Option A: VirtualBox GUI using
.ova image file
Start the VirtualBox application (“Oracle VM VirtualBox” in the Start menu).
Import Applianceor click the Import Icon. This launches the Import Virtual Appliance screen.
Select the downloaded
.ovaimage from the file system:
Local File System.
- File: path to the downloaded
Next screen is Appliance settings, where the imported VM configuration is shown and can be tweaked. There’s no need to modify these parameters unless you know what you’re doing.
Clicking Import starts importing the virtual machine.
Option B: From the Command Line using
.ova disk file
- Run the following commands:
$ RELEASE=v2022 $ REVISION=0 $ OVAFILE=./apertis_$RELEASE-sdk-amd64-sdk_$RELEASE.$REVISION.ova $ wget https://images.apertis.org/release/$RELEASE/$RELEASE.$REVISION/amd64/sdk/$OVAFILE --2022-06-14 16:20:04-- https://images.apertis.org/release/v2022/v2022.0/amd64/sdk/apertis_v2022-sdk-amd64-sdk_v2022.0.ova Resolving images.apertis.org (images.apertis.org)... 2a00:1098:0:82:1000:25:2eeb:e3bc, 18.104.22.168 Connecting to images.apertis.org (images.apertis.org)|2a00:1098:0:82:1000:25:2eeb:e3bc|:443... connected. HTTP request sent, awaiting response... 200 OK Length: 1751623680 (1.7G) [application/octet-stream] Saving to: ‘apertis_v2022-sdk-amd64-sdk_v2022.0.ova’ apertis_v2022-sdk-a 100%[===================>] 1.70G 6.10MB/s in 4m 57s 2022-06-14 16:26:01 (6.32 MB/s) - ‘apertis_v2022-sdk-amd64-sdk_v2022.0.ova’ saved [1751623680/1751623680] $ vboxmanage import $OVAFILE [...] Successfully imported the appliance.
Option C: VirtualBox GUI using
.vdi disk file
Extract the gzipped VDI image file to a local folder on your PC. The image for the virtual machine is a single file.
Start the VirtualBox application (“Oracle VM VirtualBox” in the Start menu).
Newor click the New Icon. This launches the Create New Virtual Machine screen.
Enter a name and select type and version from the menus:
Name: recommendation is to use the format
Apertis $RELEASE.$REVISION SDKe.g.
Apertis v2020.0 SDK
Debian (64 bit)
Select the RAM size. Change the values manually according to your requirements. Assign at least 50% RAM for the virtual machine if your total RAM is more than 2 GB, with 2048MB recommended as the minimum for the SDK.
Not enough RAM might cause problems while you use the SDK (for example, Eclipse might crash).
Select Use an existing virtual hard drive file and browse to the location of your unzipped file (which should have the extension
Click Create to create the virtual machine.
A few more settings need to be modified to ensure that the Apertis images boot. Select your new virtual machine and select
Ensure that the following settings are set as required:
Enable EFI (special OSes only)option
Set video memory,
Video Memory, 64MB is recommended
Be sure 3D Acceleration is disabled. Ensure
Enable 3D Accelerationis unchecked
If you want to start your virtual machine from the desktop without having to open the VirtualBox every time, you can create a desktop icon. Right-click the entry of your virtual machine on the left and choose Create Shortcut on Desktop from the menu.
If you would like additional information about creating a new virtual machine you can find it in the VirtualBox manual
Option D: From the Command Line using
.vdi disk file
- Run the following commands:
$ RELEASE=v2020 $ REVISION=0 $ wget https://images.apertis.org/release/$RELEASE/$RELEASE.$REVISION/amd64/sdk/apertis_$RELEASE-sdk-amd64-sdk_$RELEASE.$REVISION.vdi.gz --2020-06-09 16:20:04-- https://images.apertis.org/release/v2020/v2020.0/amd64/sdk/apertis_v2020-sdk-amd64-sdk_v2020.0.vdi.gz Resolving images.apertis.org (images.apertis.org)... 2a00:1098:0:82:1000:25:2eeb:e3bc, 22.214.171.124 Connecting to images.apertis.org (images.apertis.org)|2a00:1098:0:82:1000:25:2eeb:e3bc|:443... connected. HTTP request sent, awaiting response... 200 OK Length: 2363044547 (2.2G) [application/octet-stream] Saving to: ‘apertis_v2020-sdk-amd64-sdk_v2020.0.vdi.gz’ apertis_v2020-sdk-a 100%[===================>] 2.20G 6.10MB/s in 5m 57s 2020-06-09 16:26:01 (6.32 MB/s) - ‘apertis_v2020-sdk-amd64-sdk_v2020.0.vdi.gz’ saved [2363044547/2363044547] $ gunzip apertis_$RELEASE-sdk-amd64-sdk_$RELEASE.$REVISION.vdi.gz $ VDIFILE=./apertis_$RELEASE-sdk-amd64-sdk_$RELEASE.$REVISION.vdi $ VMNAME="Apertis $RELEASE.$REVISION SDK" $ vboxmanage createvm --register --name "$VMNAME" --ostype Debian_64 Virtual machine 'Apertis v2020.0 SDK' is created and registered. UUID: 6370548c-2a11-4fb8-9411-5dc2ae686a8f Settings file: '/home/user/VirtualBox VMs/Apertis v2020.0 SDK/Apertis v2020.0 SDK.vbox' $ vboxmanage modifyvm "$VMNAME" --memory 2048 --apic on --pae on --largepages off --firmware efi --accelerate3d off --vram 64 $ vboxmanage modifyvm "$VMNAME" --nictype1 virtio $ vboxmanage storagectl "$VMNAME" --name SATA --add sata $ vboxmanage storageattach "$VMNAME" --storagectl SATA --port 0 --type hdd --medium "$VDIFILE" $ vboxmanage storageattach "$VMNAME" --storagectl SATA --port 1 --type dvddrive --medium emptydrive $ vboxsdl --startvm "$VMNAME" Oracle VM VirtualBox SDL GUI version 6.0.22 (C) 2005-2020 Oracle Corporation All rights reserved.
Start the virtual machine for the first time
Use your just created desktop shortcut, or click Start in VirtualBox to start the virtual machine. The boot-up-process might take a few seconds.
On starting the virtual machine, VirtualBox might display some popup windows informing you about mouse, keyboard and color settings which might be different on the VM. Please read through the messages and click OK for all of them. If you check the Do not show this message again checkbox, you can permanently disable these popup messages for this virtual machine.
The VirtualBox manual provides more information on the mouse and keyboard settings.
Guest Additions under VirtualBox SDK images
Guest additions consist of device drivers and system applications that optimize the guest operating system for better performance and usability. They are designed to be installed inside a virtual machine after the guest operating system has been installed. For more information on the features provided by guest additions, see the VirtualBox manual.
In the context of the Apertis project, guest additions allow developers to enable full screen rendering within VirtualBox SDK images. Full screen is not the only reason to install guest additions, though. Shared folders are another very handy feature.
Before starting installation of the Guest Additions it might be helpful to adapt the keyboard layout.
It is necessary to install guest additions corresponding to the virtual box version installed.
Make sure to backup any important data you may have in your virtual machine before installing Guest Addtions. Some revisions of the Guest Additions have been known to cause issues with the Apertis SDK images.
- Start your VirtualBox Apertis machine SDK image
- Go to
Insert Guest Additions CD Image…on the VirtualBox menu bar. A virtual device will appear on the desktop.
Double-click on the
VBOXADDITIONSCD icon which should appear on your guest desktop. This will launch a file browser.
Open a terminal by right click ▸
open terminalin the guest additions folder
Run the Linux Guest Additions installation script:
$ sudo ./VBoxLinuxAdditions.run
- Reboot your virtual machine
- Verify a new directory is created under
/optwith guest additions or verify the
vboxguestmodule is loaded
You can now enjoy guest additions’ enhanced features.
Once the Guest Additions are installed successfully (the process might take a few minutes), restart the virtual machine, see here if you need help with that.
Installing the VMware display drivers
Due to a bug in VirtualBox’s guest additions, performing certain actions with the guest display (e.g. resizing) will break the rendering of certain applications, such as VSCodium. Although this has been resolved in recent Apertis releases, you must apply some manual workarounds on previous versions:
- Any v2021 release prior to v2021.6.
- Any v2022 release prior to v2022.2.
- Any v2023 release prior to v2023dev3.
If you are unsure if you need to apply the workarounds, run:
$ dpkg -l | grep xserver-xorg-video-vmware; echo $?
If this prints
1, your image does not have the fixes included, and the
workarounds must be applied.
The following commands should be run in order to install the proper drivers and update the configuration:
$ sudo apt update $ sudo apt install xserver-xorg-video-vmware $ sed -i 's/Virtual-1/Virtual1/' ~/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-desktop.xml
After this, restart the virtual machine once again for the changes to take effect.
Setting up shared folders
Go to Settings and click Shared Folders and select Add Shared
Folders (use the icon on the left hand side). Browse to the path you created
your share folder in (e.g.
C:\SHARE). Click OK and close the Settings
window. The VirtualBox VM Settings can only be edited when the VM is closed. So
please close all VMs if any should be running, before setting up a shared
Once you start the virtual machine, go to ApplicationsTerminal Emulator and run this command in the terminal:
$ sudo mount –t vboxsf HOST_DIR_NAME GUEST_DIR_NAME
$ sudo mount –t vboxsf SHARE /mnt
This command will mount the share folder to the current
Beside the manual mounting of the shared folder it is possible to enable the automatic mounting.
Please set a tick mark for the
Auto-mount option and provide a mount path e.g.
In order to access the mount path with user access rights you have to call
$ sudo usermod -a -G vboxsf "$USER"
and reboot your virtual machine afterwards. See also the VirtualBox manual.
Setting up shared clipboard
Via the shared clipboard functionality the clipboard of the guest OS can be shared with that of your host. Enter the Shared Clipboard menu item by opening the Devices menu of the virtual machine. Then select the mode according your needs, recommendation is Bidirectional because this will always make sure that both clipboards contain the same data. Further information can be found in the VirtualBox manual.
Setting up drag and drop
Oracle VM VirtualBox enables you to drag and drop content from the host to the guest, and vice versa. Enter the Drag and Drop menu item by opening the Devices menu of the virtual machine. Then select the mode according your needs, recommendation is Bidirectional because this enables drag and drop operations in both directions. Further information e.g. known limitations can be found in the VirtualBox manual.
Adjusting virtual machine window size
Once the guest additions are installed, the window size can be changed. Select the option Adjust Window Size. Then resize the window to make it appear as a normal working size.
Put the virtual machine in Fullscreen mode
You can switch the display of the SDK to fullscreen mode by selecting View in the VirtualBox menu and choosing Switch to Fullscreen.
You can still access the most important options of VirtualBox in the menu that appears at the bottom of the screen when you get close to it with your cursor.
Install VSCodium IDE
Before installing VSCodium, ensure you have followed the above directions to set up guest’s display drivers. Otherwise, VSCodium may be unusably slow.
Apertis recommends VSCodium as a default IDE for all development activities in the SDK. However, VSCodium integration into Apertis is still ongoing. In the meantime, please follow the steps below to install it manually:
$ wget -qO - https://gitlab.com/paulcarroty/vscodium-deb-rpm-repo/raw/master/pub.gpg | gpg --dearmor | sudo dd of=/usr/share/keyrings/vscodium-archive-keyring.gpg $ echo 'deb [ signed-by=/usr/share/keyrings/vscodium-archive-keyring.gpg ] https://download.vscodium.com/debs vscodium main' | sudo tee /etc/apt/sources.list.d/vscodium.list $ sudo apt update && sudo apt install codium $ codium
Uninstall the virtual machine
To uninstall the virtual machine, open VirtualBox and right click the machine you want to remove. Chose Remove from the menu.
In the following dialog you can decide if you want to remove the virtual machine from VirtualBox or if you want to delete the files containing the virtual machine from your hard drive as well. This will remove the hard drive of the virtual machine and all files saved there. Please make sure to make backups of the files you still need before deleting all files. Remove only will just delete the virtual machine from VirtualBox but leave the files containing the virtual machine intact.
We recommend running fixedfunction, hmi and development images on
real hardware, but VirtualBox
may be able to run some of our
Running non-SDK images on VirtualBox or other virtual machines is not officially supported, though many of the images do. If the image type you are interested in evaluating does not boot in VirtualBox, there is a good chance that it may boot in QEMU.
.img.bmapfiles for the image you need from the image repository
Expand the downloaded
If you have
bmaptool(recommended), use that to create a sparse file:
$ bmaptool copy filename.img.gz apertis.img
If not, expand the downloaded
.img.gzfile (this will be slower):
$ gunzip -c filename.img.gz > apertis.img
Convert the image to VirtualBox format:
$ vboxmanage convertfromraw apertis.img apertis.vdi --format VDI
You can delete the temporary
Create a new VM in the VirtualBox Manager
Use an existing virtual hard disk fileand chose the
- Modify Settings, mostly the same as for the SDK (see above)
Base Memorycan be smaller for these images: 1024M is recommended
Accessing USB dongles from the Apertis SDK VM
This section describes how to grant access to a real USB device to the Apertis SDK virtual machine.
As an example here we describe how to connect a Wi-Fi dongle on the Apertis SDK, but the same would be applicable for a Bluetooth dongle or a USB stick.
Connect the Wi-Fi dongle to any of the available USB slots in your PC/Laptop and then on the SDK click
Devices menu and select the entry for your device in the USB sub-menu.
The tick should indicate that the Wi-Fi dongle should be available in the VM, as shown in the image below