Documentation/Maemo SDK Virtual Image Tutorial/Installation

= Installation =

= Introduction =

This chapter provides a short set of instructions on how to properly install and configure Maemo SDK Virtual Image for your machine, including networking issues.

= Host hardware =

At least 2GB of RAM and an additional 15 GB of free hard disk space for Desktop image (2 GB for Server image) is required from the host machine.

= Host operating system =

You can use Linuxes (Fedora and Debian-based Linuxes such as Debian, Ubuntu, and Kunbutu have been tested), Windows (Windows XP, Windows Vista and Windows 7 tested) or Mac OS X (Leopard and Snow Leopard tested) on your host machine.

= Virtualisation software =

It is possible to use VMWare, VirtualBox or QEMU as a virtualisation environment. We strongly recommend you to use VMWare Player for some important reasons. At first, VMWare Player is free for other than the Mac OS X environment. It provides good support for host-guest communication. With VMWare Player, the USB, parallel port, CD/DVD, storage disks and TCP/IP network work properly. However, free VMWare Player does not provide support for Mac OS X, but you can use other VMWare products in Mac OS X (for example, VMWare Fusion). For VMWare Player 3.0 or 2.5 versions can be used (2.5 recommended as the first 3.x versions may have problems maintaining SSH connections).

For VirtualBox users, the functionality of free open source version is not enough, but the binary-only version (PUEL licensed) needs to be used for Maemo SDK Virtual Images. The performance of the VirtualBox PUEL version is about the same as with the VMWare environment, but licensing allows usage only for personal and evaluation purposes. VirtualBox 3.x versions are recommended.

For QEMU users, performance may be an issue. QEMU is a totally free virtualisation environment, but the performance is much worse than with VMWare or VirtualBox. Even with KQEMU QEMU Accelerator (that must be used to get a usable Maemo development environment), performance is not on the same level as with VMWare or VirtualBox.

= Required software =

To be able to install and run Maemo SDK Virtual Image you need to have both 7-Zip uncompress tool and one of the supported virtualisation environments available.


 * 7-Zip uncompress tool to uncompress Maemo SDK Virtual Image distribution archive.
 * Virtualisation software: VMWare (any VMWare product, such as VMWare Player, VMWare Workstation or VMWare Fusion), VirtualBox PUEL release or QEMU.

= Image installation =

Both Ubuntu Desktop-based and Ubuntu Server-based Maemo SDK Virtual Images have same installation process.


 * Download Maemo SDK Virtual Image
 * from the Maemo Development Environment downloads page. Basically, there are two different Maemo SDK Virtual Images: one virtual image with Ubuntu Server installed, and another one with Ubuntu Desktop. The Ubuntu Server-based image does not have a Maemo development environment (such as Scratchbox or Maemo SDKs) preinstalled and is mainly used together with Maemo ESbox Eclipse IDE as a build environment. Maemo SDK Virtual Image with Ubuntu Desktop is mainly used as an out-of-box ready Maemo development environment that has Scratchbox, Maemo Fremantle and Diablo SDK, and ESbox Eclipse IDE environments preinstalled.


 * Unzip Maemo SDK Virtual Image distribution archive
 * with 7-Zip tool according to instructions at this site. Since the virtual images are very large files (for example, an image file with Ubuntu Desktop is about 9GB), the process to uncompress the image may take several minutes, depending on how fast your machine is. Generally, it takes about 5 minutes to uncompress Ubuntu Server-based Maemo SDK Virtual Image, and about 17 minutes to uncompress Ubuntu Desktop-based Maemo SDK Virtual Image.


 * Once your virtual image has been uncompressed, it is ready to be used!
 * If you are using VMWare as a virtualisation environment, the Maemo SDK Virtual Image distribution package already provides a *.vmx description file that can be used to load Maemo virtual image.

For VirtualBox and QEMU Maemo SDK Virtual Image distribution packages do not include ready-made image description files. For VirtualBox and QEMU, it is necessary to perform some extra tasks:


 * VirtualBox:
 * Maemo SDK Virtual Image distribution file does not provide a ready-made description file (such as *.vmx for VMWare players). Therefore, you need to install the image for your environment. For more information, visit this link.


 * QEMU:
 * It is important to install KQEMU Accelerator to speed up virtual environment execution.

Examples of how to launch Maemo SDK Virtual Image with QEMU:

Starting QEMU on Linux

$ qemu -hda maemosdk_*_*.vmdk -L /usr/bin/qemu -m 512

Starting QEMU on Windows

c:&gt; qemu.exe -hda maemosdk_*_*.vmdk -L C:/QEMU/pc-bios -m 512

= Network configuration =

A networking proxy has not been configured for Maemo SDK Virtual Images by default. Therefore, if your network environment requires a proxy to enable network access from your host machine, you have to configure it in addition to your host machine also to the Maemo SDK Virtual Image, for example, for your Ubuntu Desktop or Server environment and Scratchbox installation INSIDE your Maemo SDK Virtual Image.

For more information on how to configure proxy support for Ubuntu Desktop and Server installation, see Ubuntu HOWTO: Proxy Support.

For Scratchbox, it is necessary to define the http_proxy variable in format http://host:port/. If you have to authenticate yourself to the proxy server use format http://username:password@host:port/. To enable http_proxy variable, you need to add the following lines to root login file /root/.bashrc.

http_proxy=http://username:password@host:port/ export http_proxy

= Known Issues =

Scratchbox does not initialise the resolv.conf file properly. This file defines DNS servers. Whenever Scratchbox is started, it copies /etc/resolv.conf from host PC BEFORE this file has been updated by Ubuntu NetworkManager. If the resolv.conf file is wrong, network access does not work from inside Scratchbox. A workaround is to restart Scratchbox using the following command:

$ sudo /scratchbox/sbin/sbox_ctl restart