Documentation/Maemo Eclipse Tutorial/Installing ESbox

ESbox is an Eclipse-based IDE. It is based on Eclipse Ganymede (3.4.2) and CDT (Eclipse C/C++ Development Toolkit) and PyDev (Python IDE for Eclipse) and provides C/C++, Qt4 and Python support, source editing, project building, run/debug/profiling, and Debian installation package creation and deployment. ESbox communicates transparently with Scratchbox cross-compilation environment and one or more Maemo SDKs to let you develop Maemo applications. ESbox can also flash your Maemo devices and communicate with them using the various network clients and servers available with the PC Connectivity project.

With ESbox, Scratchbox, Maemo SDK(s), and PC Connectivity installed, you can flash your Maemo device, run, debug, and profile applications locally with Maemo SDK and remotely with Maemo device, create Debian installation packages for your application and install the application to the Maemo device.

Maemo PC Connectivity must be installed to the Maemo device and host PC before all features provided by Maemo Eclipse IDE are usable. See more information from 'Maemo PC Connectivity Tutorial.


[edit] ESbox IDE

ESbox may be installed completely from an archive or added to an existing Eclipse 3.4.2 installation from Maemo update sites.

ESbox may be installed in a variety of hosts. The Supported Environments chapter describes these. The Installing ESbox IDE section describes how to install ESbox.

[edit] Supported Maemo Releases

The supported Maemo releases are:

Older releases may work but Maemo PC Connectivity is not supported on them. If you use older releases, you must manually set up networking, SSH, and SBRSH.

[edit] Scratchbox and Maemo SDK

To build and run C/C++, Qt4 or Python applications you will need to install the Maemo SDK development environment for a Linux/x86 machine (either to your host PC or to the Maemo SDK Virtual Image).

Scratchbox enables building and running programs in a transparent cross-compilation and cross-execution environment. Scratchbox 1 is the primary cross environment for Maemo Fremantle and Diablo development.

Scratchbox 2 is a newer cross compilation environment but it is not officially supported or tested for Fremantle or ESbox.

Maemo SDKs supported by ESbox and Scratchbox 1 are:

  • Maemo 4.1.2 Diablo SDK
  • Maemo 5.0.x Fremantle SDK
Older Maemo SDKs may work but are not officially supported.

Maemo SDKs are open-source, but some components installed on the Maemo device and available to the Maemo SDK rootstraps are closed-source. These Nokia closed binaries must be installed for Fremantle SDKs to operate properly under emulation.

ESbox can install Scratchbox 1, Diablo and Fremantle Maemo SDKs, and Nokia closed binaries for you for native Linux host PC or to the Ubuntu Server SDK Virtual Image using installation wizards under File > New > Other > Maemo Installers.

[edit] ESbox Development Environment

The ESbox development environment consists of Eclipse IDE, Scratchbox, one or more Maemo SDKs and Maemo device. If host PC operating system is not able to run Scratchbox and Maemo SDK natively also Maemo SDK Virtual Image is needed. These are essential to ESbox development environment and ESbox is useless without them.

ESbox does not ship with Scratchbox or any Maemo SDK, but it includes installation wizards that allow you to install them. See File > New > Other > Maemo Installers > Scratchbox 1 and ... > Scratchbox 1 Targets.

If you want to install Scratchbox and Maemo SDKs yourself, see the Maemo SDK site for more information.

For C/C++, Qt4 and Python development, you need to install some Maemo C debugging tools and scripts, Maemo C++ bindings, Maemo Python runtime and bindings and Maemo Qt4 libraries to the Maemo SDK rootstraps and Maemo device.

ESbox provides a command via Project > Validate Installed Packages menu which will do all needed installations for C/C++, Python and Qt4 development environemnts for you. This validation operation is done also automatically when you create a new C/C++, Python or Qt4 project.

[edit] Using Maemo SDK Virtual Image for non-Linux

Only Debian based Linux/x86 hosts are able to natively run Scratchbox and Maemo SDKs. In other hosts, you must run Scratchbox and the Maemo SDK inside a Maemo SDK Virtual Image. ESbox fully supports using Maemo virtual images and VMware, VirtualBox or QEMU virtualization technologies in this manner.

The Maemo Eclipse integration provides an empty Ubuntu Server based Maemo SDK Virtual Image suitable for use with VMware, VirtualBox, and QEMU. See the Maemo SDK Virtual Image project page for more information on configuring and installing Maemo SDK Virtual Images.

You will need to configure ESbox to use the chosen virtualization environment (see the chapter on setting up ESBox within a virtual machine) so that ESbox knows where to install Scratchbox and the Maemo SDKs.

The Supported Environments chapter describes the virtualization technologies supported. For ESbox, you can install a Ubuntu Server based Maemo SDK Virtual Image using installation wizard File > New > Other > Maemo Installers > Maemo SDK Virtual Image. Installation wizard will install the whole Maemo Development environment with Scratchbox and Maemo SDK for you.

[edit] Supported Environments

[edit] Host Operating Systems Supported

Supported operating systems for host PC are listed in table 5.1. Only 32-bit operating systems are supported and tested, for example Maemo does not provide official support for any 64-bit operating system.

Table 5.1: Host Operating Systems Supported for ESbox
Host Operating System Officially Supported Virtual Image Required Tested Note
Ubuntu 8.04 Hardy Yes No Yes
Ubuntu 8.10 Intrepid Yes No Yes
Ubuntu 9.04 Jaunty Yes No Yes
Ubuntu 9.10 Karmic Yes No Yes 3
Fedora 11/12 No Yes Yes 1,3
Other Linux distros No Yes No 1,2
Windows XP SP3 Yes Yes Yes
Windows Vista SP2 No Yes Yes 2
Windows 7 No Yes Yes 2
Mac OS X x86 Leopard Yes Yes Yes
Mac OS X x86 Snow Leopard Yes Yes Yes
Mac OS X PPC Leopard No Yes No 1,2
Note 1
ESbox should work if Eclipse IDE, Maemo SDK Virtual Image and Host PC Connectivity runs properly (there are known problems in this OS).
Note 2
The Host PC Connectivity has not been fully ported to this OS causing restrictions to the supported functionality.
Note 3
On newer Linux distributions, some components like GTK+ and xulrunner have changed in ways that make Eclipse difficult to launch. You need to use provided script to launch ESbox and work around the issues.
Cygwin 1.5 is part of Host PC Connectivity for Windows and works fine in Maemo environment but supports only Windows XP. Cygwin 1.7 which supports also Windows 7 and Windows Vista has problems with X11 server preventing Maemo to fully supporting Windows 7 and Windows Vista operatring systems.

[edit] Virtual Image environments supported

Maemo SDK Virtual Images support VMware, VirtualBox and QEMU virtualization technologies to use to run images. You can use technology that is the best for your host PC configuration. The recommended technology is VMware because its performance is much better than QEMU and its licensing policy is better than VirtualBox with its PUEL license that allows only personal usage for evaluation purposes.

[edit] VMware Player / Workstation / Server

Workstation or Server recommended for easiest configuration. With VMware Player, if you want to reconfigure the memory size or change the disk assignments, you need to hand-edit <codei>*.vmx</code> files. With Player, you may not be able to use official VMware Tools to accelerate the virtualization performance (because official VMware Tools may not be delivered together with the VMware Player installation) but you need to install Open VM Tools delivered together with the Maemo SDK Virtual Image.

Installation of official VMware tools or Open VM Tools (delivered with Maemo SDK Virtual Image) is recommended for better performance.

VMware Player 3.0 includes official VMware Tools and for example memory size can be configured without hand-editing *.vmx but it may have SSH connection problems. VMware Player version 2.5 is recommended over version 3.0 because 3.0 version may have problems also keeping SSH connection alive. For Mac OS X VMware Fusion must be used instead of VMware Player.

[edit] Sun VirtualBox 2.2 or Newer

VirtualBox performance is almost equal to VMware and configuration is easy, but VirtualBox Open Source version cannot be used because it does not have good enough support for USB and licensing of PUEL version restricts usage only for personal and evaluation purposes.

Installation of GuestAdditions (delivered with Maemo SDK Virtual Image) is recommended for better performance.

[edit] QEMU System Emulation

Works, but is not recommended. The performance is quite slow.

Installation of KQEMU QEMU Accelerator for QEMU is almost mandatory, if it is available for your operating system.

[edit] X Servers supported

When running or debugging locally during development, an X11 server runs on the Eclipse host PC and displays your programs in the Maemo Application Framework.

X servers are available on all supported operating systems, but the Fremantle SDK imposes some high requirements on the X server. Linux-on-Linux development will yield the best results (both quality and performance wise). On other operating systems, there are workarounds for known issues.

For Linux:

  • The Xephyr X server is recommended.
  • Installation for Debian Linux: sudo apt-get install xserver-xephyr
  • Installation for Fedora Linux: sudo yum install xorg-x11-xserver-Xephyr

For Windows:

  • The X server from the Cygwin/X project is recommended.
  • See chapter [/node8.html#sec:esbox_installation_setting_up_x_server_on_windows 6.3.1] for more details.

For Mac OS X:

  • The Xephyr X server is recommended. This runs natively in Quartz.
  • See chapter [/node8.html#sec:esbox_installation_setting_up_x_server_on_mac_os_x 6.3.2] for more details.

[edit] Installing ESbox IDE

[edit] Java Runtime

ESbox is an Eclipse application, which needs Java to run.

Eclipse 3.4.2 requires Java 1.5 or newer:

GNU gcj is not supported.

You can find these JREs as packages in your distribution or download them directly from their websites.

[edit] Method 1: Full Product Archive (recommended)

  • ESbox is distributed as a full Eclipse product archive, which contains Eclipse, the Mica framework, and ESbox. This is the easiest way to ensure you have the right versions of the plugins and features.
  • Download it, extract it, and get started! Follow the instructions for installation via product archives

[edit] Method 2: Eclipse Update Site

  • If you have a custom Eclipse 3.4.2 installation or want to build one, you can use the Eclipse Software Updates mechanism to download and install and upgrade ESbox and Mica from the Internet.
  • Newer versions of Eclipse than 3.4.x are not supported due to hard dependencies for Eclipse packages being used.
  • Follow the instructions for installation via the Maemo Update site
Both the installation via the Full Product Archive and the Eclipse Update Site can be upgraded using Eclipse's Software Updates.