• Intro
• Downloads
• Community
• Development
• News
• TALK

Documentation/Maemo Eclipse Tutorial/Getting Started with Maemo Eclipse

This document is designed to help people who are unfamiliar with Maemo Eclipse support. It presents an introduction to the Eclipse environment in general and shows how the Maemo ESbox and PluThon products encapsulate Maemo development.

Eclipse is an open-source extensible software development platform. Its roots are in developing integrated development environments (IDEs) for different languages and environments. The Eclipse framework has been used, for example, to implement development tools for languages like Java, C/C++, Python, and XML.

ESbox is a product built on Eclipse for developing C/C++ and Python applications with Maemo SDK for Maemo devices. ESbox has some special support also for Qt4 development, which uses C++ as programming language.

PluThon is a product built on Eclipse for developing Python applications without Maemo SDK for Maemo devices. With PluThon, development is done directly with a Maemo device instead of running and debugging the application first with Maemo SDK.

This chapter first presents some generic instructions and terminology useful for the Maemo Eclipse environment, and then provides actual installation and usage instructions for ESbox and PluThon.

Eclipse Workspace

The first time you start ESbox or PluThon, it asks you to choose the workspace folder figure 2.1. By default, a directory underneath the product directory is selected. Any writeable location may be used for workspace folder, but avoid directories with spaces in the name.

The workspace holds projects and configuration settings. Generally, all work is stored in projects. A project may range in scope from a single application or library to a suite of programs, tests, documentation, and so on. Projects cannot be nested, although they may refer to each other in ordering builds.

Eclipse projects have Project Natures, which determine what builders are associated with the project and what commands are available. You do not directly interact with natures; instead, new project wizards, import wizards, or project conversion wizards apply appropriate natures to the projects.

In traditional Eclipse usage, each project corresponds to a subdirectory of the workspace directory. However, in ESbox projects must be created in a location visible to Scratchbox, which is used as a base for Maemo SDK cross-compilation environment. When creating projects in ESbox always select a location inside your home directory in Scratchbox. With PluThon, programs are always copied or mounted onto a device, so the project location is more flexible.

Projects hold nested files and folders. Normally each folder corresponds to a subdirectory of the project directory, but a folder can also be linked to a directory anywhere in the filesystem. Projects, folders, files, and links are called Workspace Resources in Eclipse. Other content on your disk, such as SDK contents, are located outside the workspace and are called External Resources. Unless otherwise noted, Resources refers to workspace resources.

To see where a particular resource resides on the disk, right-click it, select Properties, and refer to the Resource node. The Location field displays the disk location.

The workspace includes an important feature: it maintains a Local History of changes done to each resource. This makes it possible to compare a previously saved resource with older revisions. This history also minimises the risk of losing resources. However, the local history is limited in size, depending on the configuration.

In addition to the local history, you can integrate support for version control systems, called Team Providers in Eclipse, to support CVS, Subversion, Mercurial, git, and so on.

Eclipse user interface

Eclipse runs in a window called Workbench. Figure 2.3 shows the most important Workbench components.

The basic elements of the environment include:

1. Workbench: Eclipse's graphical user interface, a single application window that at any given time contains a number of different types of panes called views, and one special pane, the editor area.
2. Perspective: the current set and layout of the views and editors in the workbench window. Each perspective provides several preselected sets of views arranged in a predetermined way, which means that you do not have to worry about what views to choose or how to arrange current views. Actions such as closing, opening, or rearranging views modifies the perspective.
3. View: a visual container to display a particular specialized user interface. Typically, a view contains a data grid or tree structure. As Eclipse can illustrate the same information in many different ways, it has many different kinds of views. For example, the Package Explorer view represents programming projects from a high-level perspective, while the Navigator view shows the low-level filesystem layout of the project.
4. Short Cut Bar: a set of icons that enables the user to access different perspectives quickly.
5. Menu Bar: a set of content-sensitive actions that enables the execution of some predefined function.
6. Tool Bar: a set of context-sensitive actions that enables the execution of some predefined function. All the items found within the toolbar appear within the menu bar.
7. Editor: the primary tool used to display and manipulate data. Eclipse includes different types of editors for different types of documents. When you select (or create) a document in Eclipse, it opens a default editor based on the file type. You can also explicitly select which editor to use (File -> Open With), and this preference is recorded. For example, ESbox and PluThon include specialised C/C++ and Python source editors, but you may also choose to edit source as raw text.

The workspace preferences and settings for Eclipse are contained in one main place: Windows -> Preferences. This dialog contains the union of preference settings for all the components installed into Eclipse. Make use of the Filter text field, since it can help you find topics in the pages. Almost all settings will take effect when you select Ok or Apply.

Useful shortcuts

• Ctrl-Shift-R (Cmd-Shift-R): open any resource in the workspace
• Ctrl-Shift-L (Cmd-Shift-L): quick key shortcut dialog
• Ctrl-`: (in C/C++ editor) swap header and source
• Ctrl-3: find almost any user interface in your installation

Eclipse and ESbox/PluThon

The ESbox and PluThon products add support to Eclipse for Maemo SDK and Maemo devices. To integrate ESbox and PluThon to the Maemo device, a connectivity framework called Maemo PC Connectivity needs to be installed on the Maemo device and another framework called Host PC Connectivity needs to be installed on the host PC. These PC Connectivity products implement the connectivity between the Maemo device and the host PC to create a base for the Maemo development environment.

Important entry points:

• Window -> Preferences -> Maemo: in the event of bugs, navigate here and enable Log commands. The command log is important for diagnosing problems.
• Window -> Preferences -> Maemo -> Installed Targets: the detected Maemo SDKs on your system, and the Maemo-compatible device connections are here. This tree appears in various wizards provided by these products, and sometimes in combo boxes. Anywhere this UI appears, you can get a menu of useful commands by right-clicking.
• File -> New -> Other -> Maemo Installers: the wizards for installing a full development environment, including a virtual disk image for ESbox are here.

ESbox performs builds and launches by generating essentially the same commands you would otherwise enter on the command line inside Maemo SDK, with the advantage that you do not have to manually enter them.

When not running Eclipse IDE and ESbox on a Linux/x86 host, you must use a Maemo SDK Virtual Image, because the Maemo SDK runs only on Linux/x86. ESbox transparently sends commands to the virtual image and Maemo SDK over SSH. Running Eclipse IDE and PluThon does not require Maemo SDK or Maemo SDK Virtual Image, as it uses Maemo device to launch applications.

When developing an application locally, ESbox automatically launches it in Maemo SDK (which may reside inside Maemo SDK Virtual Image) in a local X server. When launching or debugging remotely, ESbox lets you select a Maemo device and it copies your program or mounts its directory from the host PC to a Maemo device for you.

PluThon uses the PyDev project to provide Python editing and code completion. There are no project builds as Python is an interpreted programming language and thus Maemo SDK is not needed on a host PC. All launches of Python applications from Eclipse are remote, meaning no Scratchbox is needed.

Using the ESbox and PluThon Help Documentation

The ESbox and PluThon help documentation was implemented using the Eclipse IDE Help system. This system lets you browse and search help documentation. The documentation is organized into topics to make the search easier. The help system also supplies a text search capability for finding the information you need by search phrase or keyword, and context-sensitive help for finding information to describe the particular function you are working with. You can access the help system in the workbench by two ways: in a separated Help window as shown in figure 2.5 or using the Help view as shown in figure 2.6.

If you access Help in a separate Window you see a Window like figure 2.7. On the left you can see all Help Contents topics, and their information is shown on the right.

The second way of accessing Help is to make a help documentation search. For example, if you want to know more details about Maemo Targets, all you need to do is to open the Help View and search for these keywords, as shown in figure 2.8. All related topics are returned. This search can also be done in the separate Help Window.

PluThon Help Documentation can be accessed in the same way as ESbox help as shown in figure 2.9.