Documentation/Maemo Eclipse Tutorial/Using ESbox

ESbox supports C, C++, Python and Qt4 projects. This chapter briefly describes how to create different types of projects and applications and how to run, test and debug applications using Maemo SDK and a Maemo device.

ESbox requires that C/C++, Python and Qt4 development environments are installed on the host PC where Maemo SDK is run and on the Maemo device. For detailed instructions on how to install ESbox and the required development environments, see ESbox installation chapters. You need PC Connectivity to connect the Maemo device to the host PC and ESbox. For instructions on how to install and configure Maemo PC Connectivity on the Maemo device and Maemo Host PC Connectivity on the host PC where the ESbox Eclipse environment is run, see PC Connectivity documentation.

Before creating your first project with ESbox, make sure that you can connect to your Maemo device from the host PC (that PC Connectivity has been properly installed and configured).

Contents

[edit] Creating C/C++ and Qt4 Projects

[edit] C/C++ and Qt4 Templates

Templates define the basic structure of the project. Most of the templates are examples but you can also use them as a basic structure for your project.

To create a new C or C++ project, select File > New > Project, figure 8.1.

  • C > C Maemo Project
  • C++ > C++ Maemo Project

For Qt4 projects, select C++ project.

File:Project-Python-new.png
Figure 8.1: New Project Menu

ESbox supports simple Qt4, Makefile and Autotools projects, figure 8.2.

File:C-01-projects.png
Figure 8.2: New C/C++ Project

Select any of the available templates on the Template Project Type page, figure 8.3.

File:C-02-templates.png
Figure 8.3: C/C++ Project Template
Image:Ambox_notice.png
Maemo 4 templates are only for Diablo targets and Maemo 5 templates for Fremantle. Select the correct template depending on your installation.

[edit] C/C++ and Qt4 Targets

You can select multiple targets for a project. Optimized targets are compiled using compiler optimization while debug targets are compiled with debug options.

If you want to run a project on a Maemo device, select the ARMEL target. To run a project on the emulator, select the X86 target.

Select all targets for a project, figure 8.4. You can change the targets after you have created the project.

File:C-03-targets.png
Figure 8.4: C/C++ Project Target

If you do not see any targets on the Project Configuration page, check that Maemo SDK targets are installed and install them if necessary. For more information on how to install Maemo SDK and targets for ESbox, see ESbox installation chapters.

[edit] C/C++ and Qt4 Metadata

Other project pages define different metadata the template uses. You can specify additional information in the fields or use the default values, figure 8.5.

File:C-04-metadata.png
Figure 8.5: C/C++ Project Metadata

After defining the values, click Finish to create a project.

[edit] Validating C/C++ and Qt4 Project Packages for Maemo SDK

When you have created a new project, ESbox suggests package validation, figure 8.6. If you are not sure that the required development environments have been installed for your targets, click Yes.

File:C-05-validate.png
Figure 8.6: Validate Packages Dialog

ESbox installs all the required dependencies for your project for the selected targets, if they are not installed already, figure 8.7.

If ESbox asks you about changing the target, click Yes to accept. Accept and install any packages ESbox suggests, and close the package validation wizard when the installation is complete.

File:C-06-validate-wizard.png
Figure 8.7: Validate Packages Wizard

You can also validate project packages afterwards. To start the validation, select Project > Project Menu > Validate Installed Packages.

During validation, the projects are scanned for dependencies using the following information:

  • Autotools projects: PKG_CHECK_MODULES macros in configure.ac
  • Makefile projects: default metapackages for the project type and libraries detected through pkg-config invocations

[edit] Running C/C++ and Qt4 Applications on Maemo SDK

First, select the build configuration. Change the build configuration to DIABLO_X86 (Debug) or FREMANTLE_X86 (Debug)<code>.

To activate the selected configuration, right-click the project and select Build Configurations > Set active, figure 8.8.

File:C-07-set-target.png
Figure 8.8: Set C/C++ Project Target

To add or remove targets, select Manage in the same menu.

The project is ready to be launched on Maemo SDK. To launch it, right-click the project and select Run As > Maemo Local Application, figure 8.9.

File:C-08-run-as.png
Figure 8.9: Run C/C++ Project as Local Application

If Maemo Application Framework is not running, ESbox asks you to launch it. When you have launched the Application Framework successfully, you can see the Application Framework and the program running, figure 8.10.

File:C-09-result.png
Figure 8.10: C/C++ Project Local Launch Result

[edit] Running C/C++ and Qt4 Applications on a Maemo Device

To be able to run your application on a Maemo device, Maemo PC Connectivity must be installed on the device and Maemo Host PC Connectivity on the host PC. For more information, see ESbox installation chapters.

Because the device uses <code>ARMEL binaries, you must to change the target platform to DIABLO_ARMEL or FREMANTLE_ARMEL and rebuild your application for the Maemo device.

First, make sure that DIABLO_ARMEL or FREMANTLE_ARMEL target is selected by right-clicking the project and selecting Properties > Build Configurations > Manage, figure 8.11.

File:C-remote-01-manage.png
Figure 8.11: C/C++ Project Manage Target Menu

Set the target to DIABLO_ARMEL or FREMANTLE_ARMEL, figure 8.12.

File:C-remote-02-targets.png
Figure 8.12: C/C++ Project Manage Targets

Right-click the project, select Build Configurations > Set Active and activate DIABLO_ARMEL (Debug) or FREMANTLE_ARMEL (Debug), figure 8.13.

File:C-remote-03-set-target.png
Figure 8.13: Set C/C++ Project Target

[edit] Validating C/C++ and Qt4 Project Packages on a Maemo Device

To be able to run your application on the Maemo device, you need to make sure that all the required runtime dependencies for your application are available on the device.

Select Project Menu > Validate Installed Packages. On the first page, select the project to be validated, figure 8.14.

File:C-remote-04-validate-device.png
Figure 8.14: Validate Packages Menu

On the Target Selection page, select the correct Maemo device connection and ARMEL target, Figure 8.15.

File:C-remote-05-validate-targets.png
Figure 8.15: Validate Package Targets

To start the validation, click Finish on the last page. This installs the required packages for the selected project on the Maemo device.

You can also validate project packages afterwards. To start the validation, select Project > Project Menu > Validate Installed Packages.

[edit] Running C/C++ and Qt4 Projects on a Maemo Device

To be able to run your application on a Maemo device, Maemo PC Connectivity must be installed on the device and Maemo Host PC Connectivity on the host PC. For more information, see ESbox installation chapters.

After you have set the target to ARMEL and built your application as ARMEL, you can run your application on the Maemo device. To run the application, right-click the project and select Run As > Maemo Remote Application, figure 8.16.

File:C-remote-06-run.png
Figure 8.16: Run C/C++ Project as Remote Maemo Application

Select SSH as the connection type (using the SBRSH connection type requires additional configuration), figure 8.17.

File:C-remote-07-use-ssh.png
Figure 8.17: Connection Type Dialog

Select the device connection, figure 8.16. Use USB connection because it is faster than Bluetooth or WLAN.

File:C-remote-08-select-connection.png
Figure 8.18: Select Device Connection Dialog

You can now see your application running on the Maemo device.

You can use VNC Viewer to control the Maemo device and your application running on it. Select Window > Show View > Other > VNC Viewer.

Image:Ambox_notice.png
To use VNC Viewer, the x11vnc service must be installed on the Maemo device either separately (apt-get install x11vnc) or as part of Maemo PC Connectivity.

[edit] Debugging C/C++ and Qt4 Applications

To be able to debug a project, you must set at least one breakpoint into one of the source files. To add a breakpoint somewhere, open a source file, right-click on the left source side panel and select Add Breakpoint, figure 8.19.

File:C-debug-01-breakpoint.png
Figure 8.19: Adding a Breakpoint to a C/C++ Source File

To launch your project in debug mode, right-click the project and select Debug As > Maemo Local or Remote Application. When prompted, accept changing to the debug perspective, figure 8.20.

File:C-debug-02-debug.png
Figure 8.20: Debug as Maemo Application Menu

In the debug perspective, you can stop and continue the execution, step lines, inspect variables, and so on. See Figures 8.21 and 8.22.

Image:Ambox_notice.png
You can switch back and forth between perspectives by selecting from the top right corner.
File:C-debug-03-perspective.png
Figure 8.21: C/C++ Project Debug View
File:C-debug-04-variables.png
Figure 8.22: Inspect C/C++ Variables

[edit] Creating Python Projects

ESbox Python projects require that Python is installed on the host PC. For more information, see ESbox installation chapters.

[edit] Python Templates

Templates define the basic structure of the project. Most of the templates are examples but you can also use them as a basic structure for your project.

To create a new Python project, select File > New > Project and then Python Maemo Project, figure 8.23.

File:Project-Python-new.png
Figure 8.23: New Project Menu

Select any of the Python example templates on the Template page, figure 8.24.

File:Python-01-template.png
Figure 8.24: Python Project Template

[edit] Python Targets

Select DIABLO_X86 or FREMANTLE_X86 as the target, figure 8.25.

File:Python-02-target.png
Figure 8.25: Python Project Target

[edit] Python Metadata

The Basic Settings page defines different metadata the selected template uses. You can specify additional information in the fields or use the default values, figure 8.26.

File:Python-03-metadata.png
Figure 8.26: Python Project Metadata

[edit] Python Configuration

You can define the Python configuration settings on the last page. If the wizard cannot find an existing Python configuration, it suggests to create a new configuration.

You can use the default values and click Finish to a create project, figure 8.27.

File:Python-04-grammar.png
Figure 8.27: Python Project Configuration

If there is no previous configuration for your project, ESbox asks you to create a new configuration. To create one, click Yes.

For the Python interpreter configuration, you can add all the Python paths and confirm this by clicking OK, figure 8.28.

File:Python-05-path.png
Figure 8.28: Python Project Interpreter Paths

[edit] Validating Python Project Packages

When you have created a new project, ESbox suggests package validation. Click Yes to accept, figure 8.29.

File:C-05-validate.png
Figure 8.29: Validate Packages

Click Finish on the Package Validation Wizard dialog, figure 8.30. ESbox installs all the required dependencies for the selected targets.

File:C-06-validate-wizard.png
Figure 8.30: Validate Packages Wizard

If ESbox asks you about changing the target, click Yes to accept. Accept and install any packages ESbox suggests, and close the package validation wizard when the installation is complete.

You can also validate project packages afterwards. To start the validation, select Project > Project Menu > Validate Installed Packages.

During validation, the projects are scanned for dependencies using Python package imports from the source files.

[edit] Running Python Applications on Maemo SDK

First, select the build configuration. Change the build configuration to DIABLO_X86 or FREMANTLE_X86.

Right-click the project and select Properties, figures 8.31.

File:Python-06-properties.png
Figure 8.31: Python Project Properties

Select Maemo Build Configurations and activate the configuration, figures 8.32

File:Python-07-configuration.png
Figure 8.32: Python Project Build Configuration

To launch the project on Maemo SDK, right-click the project and select Run As > Python Maemo Local Application, figure 8.33.

File:Python-08-run-as.png
Figure 8.33: Python Project Run as Local Application

Select the file you want to run on Maemo SDK. Do not select setup.py because it is used only for Debian package creation, figure 8.34.

File:Python-09-run-file.png
Figure 8.34: Python Project Select File on Launch

If Maemo Application Framework is not running, ESbox asks you to launch it. When you have launched Maemo Application Framework successfully, you can see the Application Framework and the program running, figure 8.35.

File:Python-10-result.png
Figure 8.35: Python Project Local Launch Result

[edit] Running Python Applications on a Maemo Device

To be able to run your Python application on a Maemo device, Maemo PC Connectivity must be installed on the device and Maemo Host PC Connectivity on the host PC. For more information, see ESbox installation chapters.

First, make sure that DIABLO_ARMEL or FREMANTLE_ARMEL target is selected by right-clicking the project and selecting Maemo Build Configurations. Select DIABLO_ARMEL or FREMANTLE_ARMEL as the target, figure 8.36.

File:Python-remote-02-target.png
Figure 8.36: Select Python Project Target

If there is no configuration for the target, ESbox asks you to create one. To configure a new target, click Select all.

[edit] Validating Python Project Packages on a Maemo Device

To be able to run your application on a Maemo device, you need to make sure that all the required runtime dependencies for your application are available on the device.

Select Project Menu > Validate Installed Packages. On the first page, select the project to be validated, figure 8.37.

File:C-remote-04-validate-device.png
Figure 8.37: Validate Packages Menu

On the Target Selection page, select the correct Maemo device connection and ARMEL target, Figure 8.38.

File:C-remote-05-validate-targets.png
Figure 8.38: Validate Package Targets

To start the validation, click Finish on the last page. This installs the required packages for the selected project on the Maemo device.

During validation, the projects are scanned for dependencies using Python package imports from the source files.

[edit] Running Python Projects on a Maemo Device

To be able to run your application on a Maemo device, Maemo PC Connectivity must be installed on the device and Maemo Host PC Connectivity on the host PC. For more information, see ESbox installation chapters.

After you have set the target to ARMEL you can run your application on the Maemo device. To run the application, right-click the project and select Run As > Maemo Remote Application, figure 8.39.

File:Python-remote-03-run.png
Figure 8.39: Python Project Run as Remote Application

Select the Python file you want to run. Do not select setup.py because it is used only for Debian package creation. Select SSH as the connection type (using SBRSH requires additional configuration). Select the correct device connection.

You can now see your application running on the Maemo device.

You can use VNC Viewer to control the Maemo device and your application running on it. Select Window > Show View > Other > VNC Viewer.

Image:Ambox_notice.png
To be able to use VNC Viewer, the x11vnc service must be installed on the Maemo device either separately (apt-get install x11vnc) or as part of Maemo PC Connectivity.

[edit] Debugging Python Applications

To be able to debug a project, you must set at least one breakpoint into one of the source files. To add a breakpoint somewhere, open a source file, right-click on the left source side panel and select Add Breakpoint, figure 8.40.

File:Python-debug-01-breakpoint.png
Figure 8.40: Add Breakpoint to Python Project

To launch your project in debug mode, right-click the project and select Debug As > Maemo Local or Remote Application. When prompted, accept changing to the debug perspective, figure 8.41.

File:Python-debug-02-debug.png
Figure 8.41: Debug Python Project as

In the debug perspective, you can stop and continue the execution, step lines, inspect variables, and so on. See Figures 8.42 and 8.43.

Image:Ambox_notice.png
You can switch back and forth between perspectives by selecting from the top right corner.
File:Python-debug-03-perspective.png
Figure 8.42: Python Debug View
File:Python-debug-04-variables.png
Figure 8.43: Inspect Python Variables

[edit] Debian Packaging ESbox Project

You can create Debian installation packages for your C/C++, Qt4 and Python projects using ESbox wizards. ESbox also provides some tools to help in creating the Debian package structure, and building and installing the package.

[edit] Debian Package Structure

Debian structure is debian folder under project directory. If you do not have Debian structure in your project you can create it by right clicking project and choosing Debian Package > Create Debian Structure.

Python projects need setup.py script to create a Debian package and it should be in the project root folder. You can create setup.py from the last page of the Structure wizard.

ESbox does not automate the whole Debian structure creation process, so you might need to manually modify the files in debian folder. A Debian installation package is built using Makefile located at debian/rules directory. Other files are usually install scripts and metadata.

You can find complete information on the Debian installation package structure from Debian New Maintainers' Guide

[edit] Building Debian Package

ESbox can create a Debian installation package from your project by right clicking project and choosing Debian Package > Build Debian Package. If the project does not have Debian structure defined, the wizard helps you to create one. You must select the destination where the new Debian package is created.

[edit] Installing Debian Package

After you have built a Debian installation package, you can install it inside ESbox by right-clicking project and choosing Debian Package > Install Debian Package.

[edit] Importing Projects from Repository

[edit] Background

This feature assumes you know a little bit about the workings of Debian packages. If not, the full details are in The Debian GNU/Linux FAQ; Chapter 7 - Basics of the Debian package management system.

[edit] Repositories and package types

In the Debian package manager apt (used in Scratchbox and Maemo devices), the sources.list repository configuration files contain two kinds of entries: deb and deb-src repositories. Both point to external or local repositories of packages (called system packages here). deb repositories point to binary packages while deb-src repositories point to the (usually in sync) source packages for those binary packages.

One source package may generate several binary packages; for instance, one for programs and primary data, one for auxiliary data, one for libraries, and one for development.

In apt, when fetching the sources for a binary package, you start with an interesting binary package and find its corresponding source package (for example, apt-get source <package>).

[edit] Source package structure

The sources for a package come usually in three files: a control file (*.dsc), an archive (*.tar.gz or *.tar.bz2), and a patch (*.diff.gz). apt-get source command invokes the dpkg-source command to expand the archive and apply the patch. The control file is used when rebuilding the binary package.

Once extracted, the contents of the original patched sources vary wildly. The contents may contain a bare-bones Makefile project, an autotools-based project, a nest of programs and libraries and test code, or even another archive.

There is one guarantee, though: the package expands to contain a debian directory and its various control files (see the "Source packages" chapter of the Debian Policy Manual for more details).

The debian/rules file is an executable Makefile which is the primary means of interaction with the source from the perspective of a Debian package. In other words, even if the extracted sources contain autoconf files or Makefiles, you must use debian/rules to configure, build, clean, install, and re-package the package.

For example, debian/rules configure, debian/rules build, debian/rules install are typical ways to use a source package.

It must be mentioned that even debian/rules can have varying degrees of fluctuation in the targets it provides. Most packages not developed in the Debian project itself come from a large community of people who think differently, and the targets vary accordingly. While the utility dh_make tries to promote a standard set of guidelines, some projects may, for instance, lack a configure target (or have several), lack a build target (or have several), and so on.

ESbox attempts to corral this kind of diversity with its import wizard.

[edit] Using the Wizard

Find the wizard under File > Import > ESbox > Project from Debian Repository, figure 8.44.

File:ImportPackageWizard.png
Figure 8.44: Import

Select the package to import, figure 8.45.

File:ImportPackageSelect.png
Figure 8.45: Import ESbox Project from Repository - Select Package

The target providing packages is one of the Scratchbox targets on the host PC.

{{ambox |text=The target must have the necessary deb-src entries in sources.list. Standard Maemo SDK configurations have such entries by default. |}

The package selector shows a tree of packages organized by category. You can search by typing in the filter (for words in the name or description) or typing in the tree (for the name alone).

The Fetch build dependencies option ensures that, in addition to fetching the source for the selected package, any packages needed to build the source are installed as well.

The Always re-fetch source components option asks the wizard to always go to the network and find the source components (the .dsc file, archives, and patches) for the package. This may be necessary if you have modified the package locally.

The Delete source components option deletes the .dsc file, source archives, and patches after extraction.

Next, select the build targets for the package, figure 8.46.

File:ImportPackageProject.png
Figure 8.46: Import ESbox Project from Repository - Project Configuration

The next page prepares for the source fetch, figure 8.47.

File:ImportPackageFetch0.png
Figure 8.47: Import ESbox Project from Repository - Fetching and Importing, proxy

Visit the link to ensure your proxy is configured, or else the download does not work.

Press Next to start the process, figure 8.48.

File:ImportPackageFetch1.png
Figure 8.48: Import ESbox Project from Repository - Fetching and Importing, fetching

If the fetch fails then it is usually indicated by a long pause after the Building dependency tree message - press Cancel to abort the process. You can select View Log from the dialog, press Back, then press Next again to retry.

The next page lets you choose the project type and builder for the package.

This is a normal case, figure 8.49.

File:ImportPackageConvert1.png
Figure 8.49: Import ESbox Project from Repository - Convert Project

Here, the project (sysstat from earlier pages) expands into a project with a Makefile. Also (off-screen) there are C sources and headers. Thus, the wizard is able to guess the project type. This page, therefore, is merely informative and you can press Next.

An imported package may, however, be provided as a compressed archive with patches. In this case, you can preconfigure the project to extract the sources and decide whether the project is really the one you are looking for.

The following screenshot shows the inimitable bash shell, which is packaged as an archive, figure 8.50.

File:ImportPackageConvert2.png
Figure 8.50: Import ESbox Project from Repository - Convert Project, compressed archive

To handle this case, the wizard selects a build rule, which appears to be a configuration rule. This would be expected to extract the archive and apply the patches.

You can manually select the rule for configuration, if desired. For example, bash can be built in several configurations for different footprints. Here are the rules found in bash's debian/rules, figure 8.51.

File:ImportPackageConvert3.png
Figure 8.51: Import ESbox Project from Repository - Convert Project, rule selection

Select a rule and click Setup project... to run the build for the given rule. The build results go to the Console behind the wizard.

For bash, and probably other packages, this configure step actually proceeds to build the entire program and run its tests, you may Cancel after the archive has been extracted and the patches have been applied, then proceed with the wizard, figure 8.52.

File:ImportPackageConvert3b.png
Figure 8.52: Import ESbox Project from Repository - Convert Project, building

Once the configuration step has been run, the conversion page updates its guess about the project, figure 8.53.

File:ImportPackageConvert4.png
Figure 8.53: Import ESbox Project from Repository - Convert Project, updated

Once the project type and builder type are known, you can Finish the wizard.

Projects imported from Debian packages can be edited, navigated, built, and launched like normal ESbox projects. You can, of course, also recreate Debian packages from them.

[edit] Related Topics