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.

300px|thumb|Apertis SDK image running in a VM

VirtualBox Setup

VirtualBox can be configured both from its GUI or via the command line.

From the VirtualBox GUI

  • Download the required .vdi.gz for the SDK from the image repository
  • Uncompress the downloaded .vdi.gz file
  • Create a new VM in the VirtualBox Manager (MachineNew...).
  • Select Use an existing virtual hard disk file and chose the .vdi file
  • Modify Settings
    • Set base memory, SystemMotherboardBase Memory, 2048MB is recommended
    • Check the SystemMotherboardEnable EFI (special OSes only) option
    • Check the SystemProcessorEnable PAE/NX option
    • Set video memory, DisplayScreenVideo Memory, 64MB is recommended
    • Be sure 3D Acceleration is disabled. Ensure DisplayScreenEnable 3D Acceleration is unchecked
  • Boot the VM

From the Command Line

  • 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, 46.235.227.188
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.

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.

Installation Guide

This concise step-by-step installation guide is intended for VirtualBox running our Linux Apertis SDK images. Please install an up-to-date version of VirtualBox on your Host system. Find the binaries and installation instructions here.

  • Start your VirtualBox Apertis machine SDK image
  • Click menu DevicesInstall Guest Additions
  • Double-click on the VBOXADDITIONS CD icon which should appear on your guest desktop. This will launch a file browser, note the directory name
  • Open a terminal window and change directory to the above noted directory:
cd /media/user/VBox_GAs_<VBox_version>
  • Run the Linux Guest Additions installation script:
sudo ./VBoxLinuxAdditions.run
  • Reboot your virtual machine
  • Verify a new directory is created under /opt with guest additions or verify the vboxguest module is loaded

You can now enjoy guest additions’ enhanced features.

Non-SDK images

We recommend running minimal, target and development images on real hardware, but VirtualBox can run our amd64 images.

  • Download the .img.gz and .img.bmap files for the image you need from the image repository
  • Expand the downloaded .img.gz file:
    • 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.gz file (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 .img file now
  • Create a new VM in the VirtualBox Manager
    • Select Use an existing virtual hard disk file and chose the .vdi file
    • Modify Settings, mostly the same as for the SDK (see above)
      • Base Memory can be smaller for these images: 1024M is recommended
  • Boot the VM