Editing Documentation/Maemo Eclipse Tutorial/Using ESbox

To create a new C or C++ project, select '''File > New > Project''', figure [[#figure-esbox_usage_project_new|8.1]].

<div id="figure-esbox_usage_project_new">

[[Image:project-Python-new.png|frame|center|alt=Screenshot of New Project menu|Figure 8.1: New Project Menu]]

ESbox supports simple Qt4, Makefile and Autotools projects, figure [[#figure-esbox_usage_c_01_projects|8.2]].

[[Image:c-01-projects.png|frame|center|alt=Screenshot of New C/C++ project|Figure 8.2: New C/C++ Project]]

Select any of the available templates on the '''Template Project Type''' page, figure [[#figure-esbox_usage_c_02_templates|8.3]].

<div id="figure-esbox_usage_c_02_templates">

[[Image:c-02-templates.png|frame|center|alt=Screenshot of CC++ project template|Figure 8.3: C/C++ Project Template]]

|text='''Maemo 4''' templates are only for [[Open development/Maemo roadmap/Diablo|Diablo]] targets and '''Maemo 5''' templates for [[Open development/Maemo roadmap/Fremantle|Fremantle]]. Select the correct template depending on your installation.

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

Select all targets for a project, figure [[#figure-esbox_usage_c_03_targets|8.4]]. You can change the targets after you have created the project.

[[Image:c-03-targets.png|frame|center|alt=Screenshot of C/C++ project target|Figure 8.4: C/C++ Project Target]]

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

[[Image:c-04-metadata.png|frame|center|alt=Screenshot of C/C++ project metadata|Figure 8.5: C/C++ Project Metadata]]

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

<div id="figure-esbox_usage_c_05_validate">

[[Image:c-05-validate.png|frame|center|alt=Screenshot of package validation dialog|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 [[#figure-esbox_usage_c_06_validate_wizard|8.7]].

<div id="figure-esbox_usage_c_06_validate_wizard">

[[Image:c-06-validate-wizard.png|frame|center|alt=Screenshot of package validation wizard|Figure 8.7: Validate Packages Wizard]]

* Autotools projects: <code>PKG_CHECK_MODULES</code> macros in <code>configure.ac</code>

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

To activate the selected configuration, right-click the project and select '''Build Configurations &gt; Set active''', figure [[#figure-esbox_usage_c_07_set_target|8.8]].

[[Image:c-07-set-target.png|frame|center|alt=Screenshot of C/C++ project target|Figure 8.8: Set C/C++ Project Target]]

The project is ready to be launched on Maemo SDK. To launch it, right-click the project and select '''Run As &gt; Maemo Local Application''', figure [[#figure-esbox_usage_c_08_run_as|8.9]].

[[Image:c-08-run-as.png|frame|center|alt=Screenshot of C/C++ project running as a local application|'''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 [[#figure-esbox_usage_c_09_result|8.10]].

<div id="figure-esbox_usage_c_09_result">

[[Image:c-09-result.png|frame|center|alt=Screenshot of result of launching local project|'''Figure 8.10:''' C/C++ Project Local Launch Result]]

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

First, make sure that <code>DIABLO_ARMEL</code> or <code>FREMANTLE_ARMEL</code> target is selected by right-clicking the project and selecting '''Properties &gt; Build Configurations &gt; Manage''', figure [[#figure-esbox_usage_c_remote_01_manage|8.11]].

<div id="figure-esbox_usage_c_remote_01_manage">

[[Image:c-remote-01-manage.png|frame|center|alt=Screenshot of project management target menu|Figure 8.11: C/C++ Project Manage Target Menu]]

Set the target to <code>DIABLO_ARMEL</code> or <code>FREMANTLE_ARMEL</code>, figure [[#figure-esbox_usage_c_remote_02_targets|8.12]].

<div id="figure-esbox_usage_c_remote_02_targets">

[[Image:c-remote-02-targets.png|frame|center|alt=Screenshot of project management of targets|'''Figure 8.12:''' C/C++ Project Manage Targets]]

Right-click the project, select '''Build Configurations &gt; Set Active''' and activate <code>DIABLO_ARMEL (Debug)</code> or <code>FREMANTLE_ARMEL (Debug)</code>, figure [[#figure-esbox_usage_c_remote_03_set_target|8.13]].

[[Image:c-remote-03-set-target.png|frame|center|alt=Screnshot of C/C++ project target setting|Figure 8.13: Set C/C++ Project Target]]

Select '''Project Menu &gt; Validate Installed Packages'''. On the first page, select the project to be validated, figure [[#figure-esbox_usage_c_remote_04_validate_device|8.14]].

<div id="figure-esbox_usage_c_remote_04_validate_device">

[[Image:c-remote-04-validate-device.png|frame|center|alt=Screenshot of package validation menu|Figure 8.14: Validate Packages Menu]]

On the '''Target Selection''' page, select the correct Maemo device connection and <span><font face="monospace">ARMEL</font></span> target, Figure [[#figure-esbox_usage_c_remote_05_validate_targets|8.15]].

<div id="figure-esbox_usage_c_remote_05_validate_targets">

[[Image:c-remote-05-validate-targets.png|frame|center|alt=Screenshot of package validation targets|Figure 8.15: Validate Package Targets]]

After you have set the target to <code>ARMEL</code> and built your application as <code>ARMEL</code>, you can run your application on the Maemo device. To run the application, right-click the project and select '''Run As &gt; Maemo Remote Application''', figure [[#figure-esbox_usage_c_remote_06_run|8.16]].

[[Image:c-remote-06-run.png|frame|center|alt=Screenshot of running C/C++ project as a remote Maemo application|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 [[#figure-esbox_usage_c_remote_07_use_ssh|8.17]].

<div id="figure-esbox_usage_c_remote_07_use_ssh">

[[Image:c-remote-07-use-ssh.png|frame|center|alt=Screenshot of connection type dialog|Figure 8.17: Connection Type Dialog]]

Select the device connection, figure [[#figure-esbox_usage_c_remote_06_run|8.16]]. Use USB connection because it is faster than Bluetooth or WLAN.

<div id="figure-esbox_usage_c_remote_06_run">

[[Image:c-remote-08-select-connection.png|frame|center|alt=Screenshot of device selection connection dialog|Figure 8.18: Select Device Connection Dialog]]

{{ambox

|text=To use VNC Viewer, the <code>x11vnc</code> service must be installed on the Maemo device either separately (apt-get install x11vnc) or as part of Maemo PC Connectivity.

}}

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 [[#figure-esbox_usage_c_debug_01_breakpoint|8.19]].

[[Image:c-debug-01-breakpoint.png|frame|center|alt=Screenshot of adding a breakpoint to a C/C++ source file|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 &gt; Maemo Local or Remote Application'''. When prompted, accept changing to the debug perspective, figure [[#figure-esbox_usage_c_debug_02_debug|8.20]].

<div id="figure-esbox_usage_c_debug_02_debug">

[[Image:c-debug-02-debug.png|frame|center|alt=Screenshot of Maemo application debugging menu|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 [[#figure-esbox_usage_c_debug_03_perspective|8.21]] and [[#figure-esbox_usage_c_debug_04_variables|8.22]].

[[Image:c-debug-03-perspective.png|frame|center|alt=Screenshot of C/C++ project debug view|Figure 8.21: C/C++ Project Debug View]]

[[Image:c-debug-04-variables.png|frame|center|alt=Screenshot of inspecting C/C++ variables|Figure 8.22: Inspect C/C++ Variables]]

To create a new Python project, select '''File &gt; New &gt; Project''' and then '''Python Maemo Project''', figure [[#figure-esbox_usage_project_python_new|8.23]].

<div id="figure-esbox_usage_project_python_new">

[[Image:project-Python-new.png|frame|center|alt=Screenshot of new project menu|Figure 8.23: New Project Menu]]

Select any of the Python example templates on the '''Template''' page, figure [[#figure-esbox_usage_python_01_template|8.24]].

<div id="figure-esbox_usage_python_01_template">

[[Image:python-01-template.png|frame|center|alt=Screenshot of Python project template|Figure 8.24: Python Project Template]]

Select <code>DIABLO_X86</code> or <code>FREMANTLE_X86</code> as the target, figure [[#figure-esbox_usage_python_02_target|8.25]].

<div id="figure-esbox_usage_python_02_target">

[[Image:python-02-target.png|frame|center|alt=Screenshot of Python project target|Figure 8.25: Python Project Target]]

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 [[#figure-esbox_usage_python_03_metadata|8.26]].

<div id="figure-esbox_usage_python_03_metadata">

[[Image:python-03-metadata.png|frame|center|alt=Screenshot of Python project metadata|Figure 8.26: Python Project Metadata]]

You can use the default values and click '''Finish''' to a create project, figure [[#figure-esbox_usage_python_04_grammar|8.27]].

<div id="figure-esbox_usage_python_04_grammar">

[[Image:python-04-grammar.png|frame|center|alt=Screenshot of Python project configuration|Figure 8.27: Python Project Configuration]]

For the Python interpreter configuration, you can add all the Python paths and confirm this by clicking '''OK''', figure [[#figure-esbox_usage_python_05_path|8.28]].

<div id="figure-esbox_usage_python_05_path">

[[Image:python-05-path.png|frame|center|alt=Screenshot of Python project interpreter paths|Figure 8.28: Python Project Interpreter Paths]]

When you have created a new project, ESbox suggests package validation. Click '''Yes''' to accept, figure [[#figure-esbox_usage_python_c_05_validate|8.29]].

<div id="figure-esbox_usage_python_c_05_validate">

[[Image:c-05-validate.png|frame|center|alt=Screenshot of package validation|Figure 8.29: Validate Packages]]

Click '''Finish''' on the Package Validation Wizard dialog, figure [[#figure-esbox_usage_python_c_06_validate_wizard|8.30]]. ESbox installs all the required dependencies for the selected targets.

<div id="figure-esbox_usage_python_c_06_validate_wizard">

[[Image:c-06-validate-wizard.png|frame|center|alt=Screenshot of package validation wizard|'''Figure 8.30:''' Validate Packages Wizard]]

Right-click the project and select '''Properties''', figures [[#figure-esbox_usage_python_06_properties|8.31]].

<div id="figure-esbox_usage_python_06_properties">

[[Image:python-06-properties.png|frame|center|alt=Screenshot of Python project properties|Figure 8.31: Python Project Properties]]

Select '''Maemo Build Configurations''' and activate the configuration, figures [[#figure-esbox_usage_python_07_configuration|8.32]]

<div id="figure-esbox_usage_python_07_configuration">

[[Image:python-07-configuration.png|frame|center|alt=Screenshot of Python project build configuration|Figure 8.32: Python Project Build Configuration]]

To launch the project on Maemo SDK, right-click the project and select '''Run As &gt; Python Maemo Local Application''', figure [[#figure-esbox_usage_python_08_run_as|8.33]].

<div id="figure-esbox_usage_python_08_run_as">

[[Image:python-08-run-as.png|frame|center|alt=Screenshot of Pyton project run as a local application|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 [[#figure-esbox_usage_python_09_run_file|8.34]].

<div id="figure-esbox_usage_python_09_run_file">

[[Image:python-09-run-file.png|frame|center|alt=Screenshot of selecting a file on launch of a Python project|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 [[#figure-esbox_usage_python_10_result|8.35]].

<div id="figure-esbox_usage_python_10_result">

[[Image:python-10-result.png|frame|center|alt=Screenshot of the result of launching a local Python project|Figure 8.35: Python Project Local Launch Result]]

First, make sure that <code>DIABLO_ARMEL</code> or <code>FREMANTLE_ARMEL</code> target is selected by right-clicking the project and selecting '''Maemo Build Configurations'''. Select <code>DIABLO_ARMEL</code> or <code>FREMANTLE_ARMEL</code> as the target, figure [[#figure-esbox_usage_python_remote_02_target|8.36]].

<div id="figure-esbox_usage_python_remote_02_target">

[[Image:python-remote-02-target.png|frame|center|alt=Screenshot of selecting a Python project target|Figure 8.36: Select Python Project Target]]

Select '''Project Menu &gt; Validate Installed Packages'''. On the first page, select the project to be validated, figure [[#figure-esbox_usage_python_c_remote_04_validate_device|8.37]].

<div id="figure-esbox_usage_python_c_remote_04_validate_device">

[[Image:c-remote-04-validate-device.png|frame|center|alt=Screenshot of package validation menu|Figure 8.37: Validate Packages Menu]]

On the '''Target Selection''' page, select the correct Maemo device connection and <code>ARMEL</code> target, Figure [[#figure-esbox_usage_python_c_remote_05_validate_targets|8.38]].

<div id="figure-esbox_usage_python_c_remote_05_validate_targets">

[[Image:c-remote-05-validate-targets.png|frame|center|alt=Screenshot of validating package targets|'''Figure 8.38:''' Validate Package Targets]]

After you have set the target to <span><font face="monospace">ARMEL</font></span> you can run your application on the Maemo device. To run the application, right-click the project and select '''Run As &gt; Maemo Remote Application''', figure [[#figure-esbox_usage_python_remote_03_run|8.39]].

<div id="figure-esbox_usage_python_remote_03_run">

[[Image:python-remote-03-run.png|frame|center|alt=Screenshot of Python project being run as a remote application|Figure 8.39: Python Project Run as Remote Application]]

Select the Python file you want to run. Do not select <code>setup.py</code> 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.

|text=To be able to use VNC Viewer, the <code>x11vnc</code> service must be installed on the Maemo device either separately (<code>apt-get install x11vnc</code>) or as part of Maemo PC Connectivity.

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 [[#figure-esbox_usage_python_debug_01_breakpoint|8.40]].

<div id="figure-esbox_usage_python_debug_01_breakpoint">

[[Image:python-debug-01-breakpoint.png|frame|center|alt=Screenshot of adding a breakpoint to a Python project|Figure 8.40: Add Breakpoint to Python Project]]

To launch your project in debug mode, right-click the project and select '''Debug As &gt; Maemo Local or Remote Application'''. When prompted, accept changing to the debug perspective, figure [[#figure-esbox_usage_python_debug_02_debug|8.41]].

<div id="figure-esbox_usage_python_debug_02_debug">

[[Image:python-debug-02-debug.png|frame|center|alt=Screenshot of debugging a Python project|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 [[#figure-esbox_usage_python_debug_03_perspective|8.42]] and [[#figure-esbox_usage_python_debug_04_variables|8.43]].

<div id="figure-esbox_usage_python_debug_03_perspective">

[[Image:python-debug-03-perspective.png|frame|center|alt=Screenshot of Python debug view|Figure 8.42: Python Debug View]]

<div id="figure-esbox_usage_python_debug_04_variables">

[[Image:python-debug-04-variables.png|frame|center|alt=Screenshot of inspecting Python variables|Figure 8.43: Inspect Python Variables]]

Debian structure is <code>debian</code> 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 &gt; Create Debian Structure'''.

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

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

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

The sources for a package come usually in three files: a ''control file'' (<code>*.dsc</code>), an ''archive'' (<code>*.tar.gz</code> or <code>*.tar.bz2</code>), and a ''patch'' (<code>*.diff.gz</code>). <code>apt-get source</code> command invokes the <code>dpkg-source</code> 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 <code>Makefile</code> 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 <code>debian</code> directory and its various control files (see the "Source packages" chapter of the [http://www.debian.org/doc/debian-policy/ch-source.html Debian Policy Manual] for more details).

The <code>debian/rules</code> file is an executable <code>Makefile</code> 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 <code>Makefiles</code>, you must use <code>debian/rules</code> to configure, build, clean, install, and re-package the package.

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

It must be mentioned that even <code>debian/rules</code> 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 <code>dh_make</code> tries to promote a standard set of guidelines, some projects may, for instance, lack a <code>configure</code> target (or have several), lack a <code>build</code> target (or have several), and so on.

Find the wizard under '''File &gt; Import &gt; ESbox &gt; Project from Debian Repository''', figure [[#figure-esbox_usage_import_package_wizard|8.44]].

<div id="figure-esbox_usage_import_package_wizard">

[[Image:ImportPackageWizard.png|frame|center|alt=Screenshot of project import|Figure 8.44: Import]]

Select the package to import, figure [[#figure-esbox_usage_import_package_select|8.45]].

<div id="figure-esbox_usage_import_package_select">

[[Image:ImportPackageSelect.png|frame|center|alt=Screenshot of selecting a package during ESBox prject import|Figure 8.45: Import ESbox Project from Repository - Select Package]]

|text=The target must have the necessary <code>deb-src</code> entries in <code>sources.list</code>. Standard Maemo SDK configurations have such entries by default.

The '''Delete source components''' option deletes the <code>.dsc</code> file, source archives, and patches after extraction.

Next, select the build targets for the package, figure [[#figure-esbox_usage_import_package_project|8.46]].

<div id="figure-esbox_usage_import_package_project">

[[Image:ImportPackageProject.png|frame|center|alt=Screenshot of project configuration during import of ESBox project|Figure 8.46: Import ESbox Project from Repository - Project Configuration]]

The next page prepares for the source fetch, figure [[#figure-esbox_usage_import_package_fetch0|8.47]].

<div id="figure-esbox_usage_import_package_fetch0">

[[Image:ImportPackageFetch0.png|frame|center|alt=Screenshot of fetching and imprting during import of a ESBox project|Figure 8.47: Import ESbox Project from Repository - Fetching and Importing, proxy]]

Press '''Next''' to start the process, figure [[#figure-esbox_usage_import_package_fetch1|8.48]].

<div id="figure-esbox_usage_import_package_fetch1">

[[Image:ImportPackageFetch1.png|frame|center|alt=Screenshot of fetching and imprting during import of an ESBox project|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.

This is a normal case, figure [[#figure-esbox_usage_import_package_convert1|8.49]].

<div id="figure-esbox_usage_import_package_convert1">

[[Image:ImportPackageConvert1.png|frame|center|alt=Screenshot of convert a project during import of an ESBox project|Figure 8.49: Import ESbox Project from Repository - Convert Project]]

Here, the project (sysstat from earlier pages) expands into a project with a <code>Makefile</code>. 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'''.

The following screenshot shows the inimitable bash shell, which is packaged as an archive, figure [[#figure-esbox_usage_import_package_convert2|8.50]].

<div id="figure-esbox_usage_import_package_convert2">

[[Image:ImportPackageConvert2.png|frame|center|alt=Screenshot of project conversion during import of an ESBox project|Figure 8.50: Import ESbox Project from Repository - Convert Project, compressed archive]]

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 <code>debian/rules</code>, figure [[#figure-esbox_usage_import_package_convert3|8.51]].

<div id="figure-esbox_usage_import_package_convert3">

[[Image:ImportPackageConvert3.png|frame|center|alt=Screenshot of project conversion during import of an ESBox project|Figure 8.51: Import ESbox Project from Repository - Convert Project, rule selection]]

For <code>bash</code>, 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 [[#figure-esbox_usage_import_package_convert3b|8.52]].

<div id="figure-esbox_usage_import_package_convert3b">

[[Image:ImportPackageConvert3b.png|frame|center|alt=Screenshot of building during import of an ESBox project|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 [[#figure-esbox_usage_import_package_convert4|8.53]].

<div id="figure-esbox_usage_import_package_convert4">

[[Image:ImportPackageConvert4.png|frame|center|alt=Screenshot of project conversion during import of an ESBox project|Figure 8.53: Import ESbox Project from Repository - Convert Project, updated]]