maemo.org wiki - User contributions [en]

Documentation/Maemo SDK Virtual Image Tutorial/Maemo SDK Virtual Image content

2010-04-09T09:05:08Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Maemo SDK Virtual Image content =

= Introduction =

Maemo provides two different virtual images, Ubuntu Desktop and Ubuntu Server-based images. Both images can be updated from the repository using standard repository update methods. Ubuntu Intrepid Linux installation can be updated from the standard Ubuntu Intrepid repository, and Maemo development environments can be updated from Maemo Fremantle and Diablo SDK, Tools and Extras repositories.

Ubuntu Desktop-based image is an out-of-box ready development environment for Maemo that has full Fremantle and Diablo development environments preinstalled.

Ubuntu Server-based image is an empty environment, mainly for Maemo Eclipse IDE environment usage. With Server image it is possible to use a Maemo cross-compilation development environment (Scratchbox and Maemo SDK) in other than Debian-based Linuxes (as on Fedora, Windows and Mac OS X). Maemo ESbox Eclipse IDE provides an installation wizard to install empty Ubuntu Server-based Maemo SDK Virtual Image and other wizards to install the necessary Maemo Fremantle and Diablo development environments into it.

= Ubuntu Desktop-based image =

Ubuntu Desktop-based Maemo SDK Virtual Image includes:

* Ubuntu Desktop 8.10 Intrepid Ibex
* Maemo Fremantle and Diablo SDK environments
* Maemo Host PC Connectivity environment
* Maemo ESbox Eclipse IDE environment
* Firefox web browser with bookmarks for commonly used programming APIs on Maemo
* Python programming environment on Scratchbox (i386 and ARMEL targets) and on Eclipse IDE
* C/C++ programming environment on Scratchbox (i386 and ARMEL targets) and on Eclipse IDE
* Qt4 programming environment on Scratchbox (i386 and ARMEL targets) and on Eclipse IDE
* Installation wizards for virtualisation performance tools
** Installer for Official VMWare Tools
** Installer for Open VMWare Tools
** Installer for VirtualBox GuestAdditions

= Ubuntu Server-based image =

Ubuntu Server-based Maemo SDK Virtual Image includes:

* Ubuntu Server 8.10 Intrepid Ibex
* Maemo Host PC Connectivity environment (without GUI applications)
* Installation wizards for virtualisation performance tools
** Installer for Official VMWare Tools
** Installer for Open VMWare Tools
** Installer for VirtualBox GuestAdditions

Documentation/Maemo SDK Virtual Image Tutorial

2010-04-09T09:05:08Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

{| width="100%"
|
Nokia Corporation = MAEMO SDK VIRTUAL IMAGE TUTORIAL =<div class="author_info">'''maemo.org''''''18 February 2010'''</div>
|}

----

<div class="margins">

* [[{{PAGENAME}}/Preface|Preface]]
* [[{{PAGENAME}}/Glossary|Glossary]]
* [[{{PAGENAME}}/Introduction|Introduction]]
* [[{{PAGENAME}}/Maemo SDK Virtual Image content|Maemo SDK Virtual Image content]]
* [[{{PAGENAME}}/Installation|Installation]]
* [[{{PAGENAME}}/Summary|Summary]]
* [[{{PAGENAME}}/Bibliography|Bibliography]]

</div>

----

Documentation/Maemo SDK Virtual Image Tutorial/Installation

2010-04-09T09:05:07Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= 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.

* [http://www.7-zip.org/download.html 7-Zip] uncompress tool to uncompress Maemo SDK Virtual Image distribution archive.
* Virtualisation software: [http://www.vmware.com/ VMWare] (any VMWare product, such as VMWare Player, VMWare Workstation or VMWare Fusion), [http://www.virtualbox.org/ VirtualBox] PUEL release or [http://www.qemu.org/ 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 [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php 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 [http://maemovmware.garage.maemo.org/2nd_edition/installation_7zip.html 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 <nowiki>*.vmx</nowiki> 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 <nowiki>*.vmx</nowiki> for VMWare players). Therefore, you need to install the image for your environment. For more information, visit [http://maemovmware.garage.maemo.org/2nd_edition/create_vbox_machine.html 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:> 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 [http://ubuntuforums.org/showthread.php?t=1575 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

Documentation/Maemo SDK Virtual Image Tutorial/Glossary

2010-04-09T09:05:07Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Glossary =

; '''ARMEL'''
: A name that e.g. Debian uses for the little endian ARM EABI (''ABI'' for the ARM architecture).
; '''ESbox'''
: Eclipse product implementing integration between Eclipse IDE and Maemo SDK.
; '''GUI'''
: Graphical User Interface.
; '''IDE'''
: Integrated Development Environment like Eclipse or QtCreator.
; '''IP'''
: Internet Protocol is a protocol used for communicating data across a packet-switched internetwork.
; '''Maemo'''
: Software platform for mobile devices developed by Nokia, based on GNU/Linux and GNOME/GTK+ technologies. It includes proprietary components to make it work on the Nokia Maemo compatible device.
; '''maemo.org'''
: Developer community web site maintained by Nokia, main point of reference for open source and third-party developers in general.
; '''OProfile'''
: System-wide profiler for Linux systems.
; '''OS'''
: Operating System or sometimes Open Source.
; '''Scratchbox'''
: cross-compilation toolkit designed to make embedded Linux application development easier and to cross-compile an entire Linux distribution.
; '''SDK'''
: Software Development Kit.
; '''Valgrind'''
: Tool suite for debugging and profiling Linux programs.
; '''VM'''
: Virtual Machine.

= Maemo Releases =

; '''Mistral'''
: Maemo 2.0 release for Nokia 770 device. Corresponds to the Nokia Internet Tablet SE 2006 version 2.01.2006.26-8.
; '''Scirocco'''
: Maemo 2.1 release for Nokia 770 device. Includs mainly bugfixes and some other enhancements. Corresponds to Nokia Internet Tablet SE 2006 version 2.2006.39-14.
; '''Gregale'''
: Maemo 2.2 release for Nokia 770 device (bugfixes and enhancements).
; '''Bora'''
: Maemo 3.x releases for Nokia N800 device. Corresponds to Internet Tablet OS releases "1.2006.47-20", "2.2006.51-6" (Maemo 3.0), "3.2007.10-7" (Maemo 3.1) and "4.2007.26-8"+"4.2007.38-2" (Maemo 3.2).
; '''Chinook'''
: Maemo 4.0.x releases for Nokia N800 and N810 devices. Corresponds to Internet Tablet OS releases "1.2007.44-4" (Maemo 4.0) and "2.2007.51-3" (Maemo 4.0.1)
; '''Diablo'''
: Maemo 4.1.x releases for Nokia N800, N810 and N810 WiMAX devices. Corresponds to Internet Tablet OS releases "4.2008.23-14" (Maemo 4.1), "4.2008.36-5" (Maemo 4.1.1) and "5.2008.43-7" (Maemo 4.1.2)
; '''Fremantle'''
: Maemo 5.x releases for N900 device. Corresponds to Maemo 5 OS release "1.2009.42-11" + eMMC content "1.2009.41-1" (Maemo 5) and OS release "2.2009.51-1" + eMMC content "1.2009.41-1" (Maemo 5 Update)
; '''Harmattan'''
: Maemo 6.x releases, corresponds to Maemo 6 OS release "x.2010.xx-x"

Documentation/Maemo SDK Virtual Image Tutorial/Introduction

2010-04-09T09:05:06Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Introduction =

Maemo SDK Virtual Images are a good option for those developers who do not want to spend time and effort to download, install and configure the Linux environment and all required tools for Maemo applications development.

Maemo SDK Virtual Image support following Maemo devices and platform releases:

* Nokia N800, N810 and N810 WiMAX Edition with Diablo 4.1.x.
* Nokia N900 with Fremantle 5.x, see figure [[#fig:sdk-virtual-image-introduction-n900|1.1]].

{| summary="Maemo device - N900"
|+ align="BOTTOM" |'''Figure 1.1:''' Maemo device - N900
|-
|
[[Image:Nokia_N900_39.png|Image Nokia_N900_39]]
|}

The Ubuntu Desktop-based Maemo SDK Virtual Image is an especially good choice to be used in Maemo development workshops and training sessions as it does not require any special configuration for attendees machines. It significantly reduces the dependencies of the host machine, such as installed operating system, other software and superuser privileges. All you need to do is install the virtualisation software of your choice to the host machine and deploy Maemo SDK Virtual Image for it. With this setup, attendees can launch the virtualisation environment (such as VMWare Player) as guest users without ever accessing the host environment with administration privileges. Inside Maemo SDK Virtual Image users have, of course, full administration privileges for the Ubuntu and Maemo SDK environments.

Do not hesitate to use Maemo SDK Virtual Images, they were created to make Maemo application development a lot easier!

----

Documentation/Maemo SDK Virtual Image Tutorial/Bibliography

2010-04-09T09:05:06Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

== Bibliography ==

; 1
: Maemo Eclipse Tutorial. <tt>http://library.maemodocs.nokia.com</tt>.
; 2
: Maemo PC Connectivity Tutorial. <tt>http://library.maemodocs.nokia.com</tt>.
; 3
: Oprofile Project. <tt>http://oprofile.sourceforge.net/</tt>.
; 4
: Maemo Python Project. <tt>http://pymaemo.garage.maemo.org/</tt>.
; 5
: QEMU Project. <tt>http://fabrice.bellard.free.fr/qemu/</tt>.
; 6
: Scratchbox Project. <tt>http://scratchbox.org/</tt>.
; 7
: Ubuntu Project. <tt>http://www.ubuntu.com/</tt>.
; 8
: Valgrind Project. <tt>http://valgrind.org/</tt>.

----

Documentation/Maemo SDK Virtual Image Tutorial/Summary

2010-04-09T09:05:05Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Summary =

More information about the products included to the Ubuntu Desktop-based Maemo SDK Virtual Image can be found from these www sites and documents, Maemo Python site <ref name=r4>Maemo Python Project. http://pymaemo.garage.maemo.org/</ref>, QEMU site <ref name=r5>QEMU Project. http://fabrice.bellard.free.fr/qemu/</ref>, Scratchbox site <ref name=r6>Scratchbox Project. http://scratchbox.org/</ref>, Ubuntu site <ref name=r7>Ubuntu Project. http://www.ubuntu.com/</ref>, Valgrind site <ref name=r8>Valgrind Project. http://valgrind.org/</ref>, OProfile site <ref name=r3>Oprofile Project. http://oprofile.sourceforge.net/</ref>, ''Maemo PC Connectivity Tutorial'' <ref name=r2>Maemo PC Connectivity Tutorial. http://library.maemodocs.nokia.com</ref>, and ''Maemo Eclipse Tutorial''<ref name=r1>Maemo Eclipse Tutorial. http://library.maemodocs.nokia.com</ref>.

Current "under development" versions of the documentation can be found from [http://maemovmware.garage.maemo.org/ Maemo SDK Virtual Image] Garage project.

Current Maemo SDK Virtual Image versions can be downloaded from the [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php Maemo Development Environment Downloads] page.

----
== References ==
<references />

Documentation/Maemo PC Connectivity Tutorial/Installation

2010-04-09T09:05:04Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Installation =

The Maemo PC Connectivity product consists of two parts, Maemo PC Connectivity that installs the necessary services and configuration tools to the Maemo device, and the operating-system-specific Host PC Connectivity that installs the necessary clients to the host PC to be used to access Maemo PC Connectivity services from the Maemo device. The Maemo PC Connectivity product includes many standard services available for Linux PCs by default. Most of the services require some user expertise to be able to install and configure them properly. Maemo PC Connectivity aims to provide easy installation and configuration of these services for both the Maemo device and the host PC, and also support for other than just Linux host PC operating systems.

Maemo PC Connectivity fully supports the Maemo Fremantle platform and devices (such as N900) and the Maemo Diablo platform and devices (such as N800, N810 and N810 WiMAX).

The host PC operating systems supported are Linuxes, Mac OS X Leopard and Snow Leopard, Windows XP SP3, Windows Vista SP2 and Windows 7. On Windows and Mac OS X PCs it is required to install special Linux porting framework before Host PC Connectivity installation in order to fully utilise Maemo PC Connectivity functionality.

; '''Cygwin'''
: is a Linux-like environment for Windows. With Cygwin <ref name=r1>Cygwin Project. http://cygwin.org/</ref> installed, users have access to many standard UNIX utilities. They can be used from one of the provided shells (such as bash) or from the Windows Command Prompt. Additionally, programmers may write Win32 console or GUI applications that make use of the standard Microsoft Win32 API and/or the Cygwin API. As a result, it is possible to easily port many significant UNIX programs without the need for extensive changes to the source code. This includes configuring and building most of the available GNU software (including the development tools included with the Cygwin distribution).
; '''MacPorts'''
: is an easy-to-use system for compiling, installing, and upgrading either command-line, X11 or Aqua based open-source software on the Mac OS X operating system. MacPorts <ref name=r2>MacPorts Project. http://www.macports.org/</ref> project provides the command-line driven Linux-like software packages, and through them easy access to thousands of ports that simplify the task of compiling and installing open-source software on your Mac.

Maemo PC Connectivity provides an easy-to-install meta package maemo-pc-connectivity on the maemo.org extras repository, which installs the necessary components on the Maemo device, and separate operating-system-specific host-pc-connectivity installation packages on maemo.org Garage, which install the components needed on the host PC.

= Installation To Maemo Device =

Maemo PC Connectivity fully supports the Maemo Fremantle platform and devices (such as N900) and the Maemo Diablo platform and devices (like N800, N810 and N810 WiMAX).

== One-Click-Install ==

The easiest way to install maemo-pc-connectivity to the Maemo device is to use the one-click-install file.

To do this on Diablo, point the browser to this [http://pc-connectivity.garage.maemo.org/maemo-pc-connectivity-diablo.install address]. When the download dialog appears, choose the '''Open''' option. Now the Application Manager should open and install maemo-pc-connectivity and all its dependencies.

If you use Fremantle, you should use this [http://pc-connectivity.garage.maemo.org/maemo-pc-connectivity-fremantle.install address] for one-click-installation with a Maemo device.

== Installing with Application Manager ==

To install Maemo PC Connectivity on a Fremantle-based Maemo device, the Maemo extras-devel repository must be added. To do this, open the Application Manager, then Repository catalogs (see figure [[#fig:pc_connectivity_mpc_maemo_repository|2.3]]) and fill in the following fields:

* '''Catalogue Name:''' Maemo extras-devel
* '''Web Address:''' http://repository.maemo.org/extras-devel
* '''Distribution:''' fremantle
* '''Components:''' free non-free

If you use Diablo, replace the value of the '''Distribution''' field from fremantle to diablo and use Maemo extras repository instead of extras-devel.

{| summary="New catalogue"
|+ align="BOTTOM" |'''Figure 2.1:''' New catalogue
|-
|
[[Image:mpc_maemo_repository.png|Image mpc_maemo_repository]]
|}

Next, install the maemo-pc-connectivity package. This package installs all the Maemo PC Connectivity components.

== Installing VNC for a Diablo Device ==

To get X11VNC working properly on a Diablo device, you must install a modified version of the Diablo platform hildon-desktop package.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' On Fremantle, the VNC is already installed by maemo-pc-connectivity package.
|}

To install X11VNC to a Maemo Diablo device and update the modified hildon-desktop package, follow these steps:

Add the line below to the /etc/apt/sources.list file on your Maemo device:

deb http://pc-connectivity.garage.maemo.org/repository diablo free

Execute the following commands:

$ apt-get update
$ apt-get install x11vnc
$ apt-get install hildon-desktop

= Installation To Host PC =

The host PC operating systems supported are Linuxes, Mac OS X Leopard and Snow Leopard, Windows XP, Windows Vista and Windows 7. On Windows and Mac OS X PCs it is required to install Linux as a porting framework before Host PC Connectivity installation in order to fully utilise the Maemo PC Connectivity functionality.

== Linux - Ubuntu ==

Ready-made installation packages currently available are for Ubuntu Intrepid systems.

You must follow these steps to install Maemo PC Connectivity on Ubuntu Linux:

Open Synaptic application, figure [[#fig:pc_connectivity_mpc_linux_synaptic_open|2.2]].

{| summary="Start Synaptic"
|+ align="BOTTOM" |'''Figure 2.2:''' Start Synaptic
|-
|
[[Image:mpc_linux_synaptic_open.png|Image mpc_linux_synaptic_open]]
|}

Under the '''Settings''' menu, select the '''Repository''' option, figure [[#fig:pc_connectivity_mpc_maemo_repository|2.3]].

{| summary="Repositories"
|+ align="BOTTOM" |'''Figure 2.3:''' Repositories
|-
|
[[Image:mpc_linux_synaptic_repository.png|Image mpc_linux_synaptic_repository]]
|}

Click on the '''Add''' button to add a new repository, figure [[#fig:pc_connectivity_mpc_linux_synaptic_repository_add|2.4]]. You must type in the following repository information:

deb http://pc-connectivity.garage.maemo.org/repository intrepid main

{| summary="Third-Party Software"
|+ align="BOTTOM" |'''Figure 2.4:''' Third-Party Software
|-
|
[[Image:mpc_linux_synaptic_repository_add.png|Image mpc_linux_synaptic_repository_add]]
|}

Click on the '''Close''' button. To get all information about the packages available on the added repository, click on the '''Reload''' button, figure [[#fig:pc_connectivity_mpc_linux_synaptic_reload|2.5]].

{| summary="Reload"
|+ align="BOTTOM" |'''Figure 2.5:''' Reload
|-
|
[[Image:mpc_linux_synaptic_reload.png|Image mpc_linux_synaptic_reload]]
|}

in the '''Quick search''' field, type host-pc-connectivity. The host-pc-connectivity package is displayed on the list, figure [[#fig:pc_connectivity_mpc_linux_synaptic_select_package|2.6]].

{| summary="Mark for Installation"
|+ align="BOTTOM" |'''Figure 2.6:''' Mark for Installation
|-
|
[[Image:mpc_linux_synaptic_select_package.png|Image mpc_linux_synaptic_select_package]]
|}

Right-click on the host-pc-connectivity package. Select the '''Mark for installation''' option and click on the '''Apply''' button, figure [[#fig:pc_connectivity_mpc_linux_synaptic_install_package|2.7]].

{| summary="Apply"
|+ align="BOTTOM" |'''Figure 2.7:''' Apply
|-
|
[[Image:mpc_linux_synaptic_install_package.png|Image mpc_linux_synaptic_install_package]]
|}

Follow the instructions on the screen. After that, Host PC Connectivity is installed on your host PC.

If you prefer, you can install Host PC Connectivity manually. First, you must add the following line to the /etc/apt/sources.list file:

deb http://pc-connectivity.garage.maemo.org/repository intrepid main

Then you should run:

$ apt-get update
$ apt-get install host-pc-connectivity

== Linux - Fedora ==

It is necessary to add the Host PC Connectivity repository to the host PC repository list in order to install the host-pc-connectivity package. As Fedora does not have any graphical application for adding a new repository, all processes, repository additions and host-pc-connectivity installations are described through the command line.

To enable the Host PC Connectivity repository on Fedora Linux 11, you must add the following lines at the end of the /etc/yum.conf file:

[pc-connectivity]
name=PC-Connectivity Fedora $releasever - $basearch
failovermethod=priority
baseurl=http://pc-connectivity.garage.maemo.org/yum/base/$releasever/$basearch
enabled=1
gpgcheck=0

Then, to install the host-pc-connectivity package, you must only execute:

$ yum check-update
$ sudo yum install host-pc-connectivity

== Microsoft Windows ==

To install PC-Connectivity.exe on a Windows XP, Windows Vista or Windows 7 system, you must install Cygwin before the Host PC Connectivity installation. You can download the Cygwin installation package from [http://www.cygwin.com/ here]. If you are using a Windows 7 or Vista version, install Cygwin 1.7 or later. For Windows XP, install Cygwin version 1.5 if you run into any problems with Cygwin 1.7.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Current Cygwin 1.7 releases have problems with X11 in the Maemo environment because they do not yet implement all needed X11 extensions (such as composite). If you plan to use a Windows environment with Maemo ESbox Eclipse IDE it is recommended to use Windows XP SP3 with Cygwin 1.5 because that combination has been tested to work. Cygwin 1.5 can be installed from this [http://www.cygwin.com/setup-legacy.exe Cygwin legacy product] link.
|}

Remember to choose a installation path on your system without spaces during installation. Besides the default packages of Cygwin, the Maemo environment also requires the following optional packages to be installed:

* Admin/cygrunsrv
* Net/nfs-server
* Net/openssh
* Net/rsync
* X11/xinit
* X11/xdpyinfo

After Cygwin has been succesfully installed, download the latest PC-Connectivity.exe installer from [https://garage.maemo.org/frs/?group_id=801 PC Connectivty Garage] project. Run the installation and follow the on-screen instructions given during installation.

The installer configures the SSHD. Install it as a service and start it. On Windows 7 and Vista, the Cygwin configuration script creates a new user with administrator privileges and with a random password for the SSHD service. This new user is used to run the SSHD service independently on a user who has been logged in to the Windows PC.

== Mac OS X ==

To install Host PC Connectivity on Mac OS X Leopard or Snow Leopard, you must first switch on the Bluetooth network to be able to configure it for Maemo usage. To do this, follow these steps:

Open '''System Preferences''' under the '''Hardware''' category, and select the '''Bluetooth''' option, figure [[#fig:pc_connectivity_mpc_mac_isntalling_bt|2.8]].

{| summary="Bluetooth"
|+ align="BOTTOM" |'''Figure 2.8:''' Bluetooth
|-
|
[[Image:mpc_mac_installing_bt.png|Image mpc_mac_installing_bt]]
|}

Make sure Bluetooth is '''On''' and '''Discoverable''', figure [[#fig:pc_connectivity_mpc_mac_installing_bt_discoverable|2.9]]. Then, click on the '''Advanced''' button.

{| summary="Advanced"
|+ align="BOTTOM" |'''Figure 2.9:''' Advanced
|-
|
[[Image:mpc_mac_installing_bt_discoverable.png|Image mpc_mac_installing_bt_discoverable]]
|}

Select the '''Share my Internet connection with other Bluetooth devices''' option, figure [[#fig:pc_connectivity_mpc_mac_installing_bt_internet|2.10]].

{| summary="Share my Internet connection with other Bluetooth devices"
|+ align="BOTTOM" |'''Figure 2.10:''' Share my Internet connection with other Bluetooth devices
|-
|
[[Image:mpc_mac_installing_bt_internet.png|Image mpc_mac_installing_bt_internet]]
|}

Click the '''OK''' button to finalise the configuration.

After Bluetooth has been succesfully configured, download the latest PC-Connectivity.dmg installer file from [https://garage.maemo.org/frs/?group_id=801 PC Connectivity Garage] project. Open the installer and follow the on-screen installation instructions.

To have an environment similar to Cygwin on Windows, you can install MacPorts on Mac OS. The MacPorts project is an open-source community initiative to design an easy-to-use system for compiling, installing, and upgrading either command-line, X11 or Aqua-based open-source software on the Mac OS X operating system. You can find the MacPorts documentation and installation packages from the [http://www.macports.org MacPorts] project site.

== References ==
<references />

Documentation/Maemo PC Connectivity Tutorial/Automatic Service Publishing

2010-04-09T09:05:04Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Automatic Service Publishing =

Maemo PC Connectivity automatically announces Samba shares, NFS shares, SSH, X11VNC and SBRSH through Avahi. Due to this, host PCs can easily find the services available from a Maemo device. Avahi is an open-source implementation of the ZeroConf. It is used to facilitate the discovery of services on a local network. It allows a Maemo device to publish and discover services and hosts running on a local network with no specific configuration. For example, you can plug in a Maemo device to a network and a Linux or Mac OS X host PC instantly finds disk shares and other network services running on your Maemo device.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Avahi has not yet been included in Host PC Connectivity for Windows and thus automatic Maemo device service publishing does not work with Windows host PCs.
|}

= Using Avahi on Linux =

First, you should install avahi-discover by executing the following command:

$ sudo apt-get install avahi-discover

Next, you can use the avahi-discover utility to see all services announced by the Maemo device, figure [[#fig:pc_connectivity_mpc_linux_avahi_discover|7.1]].

{| summary="Linux Avahi Discovery dialog"
|+ align="BOTTOM" |'''Figure 7.1:''' Linux Avahi Discovery dialog
|-
|
[[Image:mpc_linux_avahi_discover.png|Image mpc_linux_avahi_discover]]
|}

= Using Avahi on Mac OS X =

Samba and NFS shares from a Maemo device are automatically shown in the '''SHARED''' section of the '''Finder''' application, figure [[#fig:pc_connectivity_mpc_mac_avahi_finder|7.2]].

{| summary="Mac OS X Finder application"
|+ align="BOTTOM" |'''Figure 7.2:''' Mac OS X Finder application
|-
|
[[Image:mpc_mac_avahi_finder.png|Image mpc_mac_avahi_finder]]
|}

Documentation/Maemo PC Connectivity Tutorial/Configuring Backup

2010-04-09T09:05:03Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Configuring Backup =

You can use the Maemo Backup tool on a Maemo device to back up the Maemo PC Connectivity configuration. The connection environments and the configuration of connections and tools are backed up. Following the steps below, you can upgrade the Maemo device platform version (reflash the Maemo device) and restore all Maemo PC Connectivity configuration after upgrade.

* Open the backup tool at '''Settings - Backup/Restore''' menu options.
* Create a backup configuration selecting at least the '''Settings''' option. If, besides the configuration, you want the software list to be in the backup, you can also select the '''Applications''' option.

Your backup can now be created. This backup can be updated anytime you want. After you have upgraded the Maemo device or reflashed it, you should simply go to the backup tool again, choose the '''Settings - Backup/Restore''' menu option and restore the backup that was created before the upgrade.

Restoring the backup may require a reboot for your Maemo device. After that, all your Maemo PC Connectivity configuration should have been restored.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Backup is stored on the memory card of your Maemo device. If you plan to flash also your memory card with an eMMC image (possible only with Maemo Fremantle devices) you need to copy backup files from the memory card to the host PC before flashing the eMMC image and back to memory card after eMMC flashing in order to restore the backup.
|}

----

Documentation/Maemo PC Connectivity Tutorial

2010-04-09T09:05:03Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

{| width="100%"
|
Nokia Corporation = MAEMO PC CONNECTIVITY TUTORIAL =<div class="author_info">'''maemo.org''''''18 February 2010'''</div>
|}

----

<div class="margins">

* [[{{PAGENAME}}/Preface|Preface]]
* [[{{PAGENAME}}/Glossary|Glossary]]
* [[{{PAGENAME}}/Introduction|Introduction]]
* [[{{PAGENAME}}/Installation|Installation]]
* [[{{PAGENAME}}/Configuration|Configuration]]
* [[{{PAGENAME}}/Network Sharing|Network Sharing]]
* [[{{PAGENAME}}/Remote Access|Remote Access]]
* [[{{PAGENAME}}/File Sharing|File Sharing]]
* [[{{PAGENAME}}/Automatic Service Publishing|Automatic Service Publishing]]
* [[{{PAGENAME}}/Configuring Backup|Configuring Backup]]
* [[{{PAGENAME}}/Bibliography|Bibliography]]

</div>

----

Documentation/Maemo PC Connectivity Tutorial/Glossary

2010-04-09T09:05:02Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Glossary =

; '''ABI'''
: Application Binary Interface, providing object code level compatibility.
; '''API'''
: Application Programming Interface, providing source code level compatibility.
; '''applet'''
: A small application that integrates to ''Hildon Desktop''.
; '''ARMEL'''
: A name that, for example, Debian uses for the little endian ARM EABI (''ABI'' for the ARM architecture).
; '''avahi'''
: is a free Zeroconf implementation that allows programs to publish and discover services and hosts running on a local network with no specific configuration.
; '''Bluetooth'''
: is an open wireless protocol for exchanging data over short distances (using short-length radio waves) from fixed and mobile devices, creating personal area networks (PANs).
; '''CIFS'''
: Common Internet File System (also known as Server Message Block, SMB) operates as an application-layer network protocol, mainly used to provide shared access to files, printers, serial ports, and miscellaneous communications between nodes on a network.
; '''CVS'''
: Concurrent Versions System.
; '''devkit'''
: The part of ''Maemo SDK'' that contains software development tools. Maemo SDK contains multiple devkits.
; '''DHCP'''
: Dynamic Host Configuration Protocol is a computer networking protocol used by hosts (DHCP clients) to retrieve IP address assignments and other configuration information.
; '''ESbox'''
: An Eclipse product implementing integration between Eclipse IDE and Maemo SDK.
; '''FHS'''
: Filesystem Hierarchy Standard defines the main directories and their contents in Linux operating systems.
; '''FUSE'''
: Filesystem in Userspace is a loadable kernel module for Unix-like computer operating systems that allows non-privileged users to create their own file systems without editing the kernel code.
; '''GDB'''
: GNU Project debugger.
; '''GUI'''
: Graphical User Interface.
; '''GTK'''
: Toolkit for creating graphical user interfaces with support for cross platform compatibility.
; '''Hildon'''
: An application framework used in the ''Maemo platform''. Developed by Nokia and based on GNOME/GTK+ technologies, currently in the process of becoming an upstream project in gnome.org.
; '''Hildon Desktop'''
: The main user interface component of Maemo Chinook, a rewrite of ''Maemo desktop''.
; '''ID'''
: Identifier.
; '''IDE'''
: Integrated Development Environment, such as Eclipse or QtCreator.
; '''IP'''
: Internet Protocol is a protocol used for communicating data across a packet-switched internetwork.
; '''ltrace'''
: A debugging utility for monitoring the library calls used by a program and all the signals it receives. It can also show system calls used by the program.
; '''Maemo'''
: A software platform for mobile devices developed by Nokia, based on GNU/Linux and GNOME/GTK+ technologies. It includes proprietary components to make it work on Nokia Maemo compatible devices.
; '''maemo.org'''
: A developer community website maintained by Nokia, and the main point of reference for open source and third-party developers in general.
; '''NFS'''
: Network File System is a network file system protocol allowing a user on a client computer to access files over a network in a manner similar to how local storage is accessed.
; '''OProfile'''
: A system-wide profiler for Linux systems.
; '''OS'''
: Operating System or sometimes Open Source.
; '''PluThon'''
: An Eclipse product implementing on-device Python development environment.
; '''rdesktop'''
: An open source client for Windows Terminal Services, capable of natively speaking RDP in order to present the user's Windows graphical desktop on another network computer.
; '''RDP'''
: Remote Desktop Protocol is a proprietary protocol developed by Microsoft, which provides a way to present the user's Windows graphical desktop on another network computer.
; '''RFB'''
: Remote FrameBuffer is a simple protocol for remote access to graphical user interfaces applicable to all windowing systems and applications, including X11, Windows and Macintosh. The protocol is used in VNC and its derivatives.
; '''rootstrap'''
: Part of the SDK that contains selected software components from rootfs. Rootstrap is the root file system of a target inside Scratchbox.
; '''rsync'''
: A software application which synchronizes files and directories from one location to another while minimizing data transfer using delta encoding when appropriate.
; '''Samba'''
: A free software re-implementation of SMB/CIFS networking protocol providing file and print services for various Microsoft Windows clients, it can integrate with a Windows Server domain.
; '''SBRSH'''
: Scratchbox Remote Shell remote command execution system similar to RSH and SSH and designed for slow devices, with Scratchbox's special requirements in mind.
; '''Scratchbox'''
: A cross-compilation toolkit designed to make embedded Linux application development easier and to cross-compile an entire Linux distribution.
; '''SCP'''
: Secure Copy is a means of securely transferring computer files between a local and a remote host or between two remote hosts. It is based on the SSH protocol.
; '''SDK'''
: Software Development Kit.
; '''SFTP'''
: SSH File Transfer Protocol (sometimes called Secure File Transfer Protocol) is a network protocol that provides file access, file transfer, and file management functionality over any reliable data stream.
; '''SMB'''
: Server Message Block (also known as Common Internet File System, CIFS) operates as an application-layer network protocol mainly used to provide shared access to files, printers, serial ports, and miscellaneous communications between nodes on a network.
; '''SSH'''
: Secure Shell network protocol that allows data to be exchanged using a secure channel between two networked devices.
; '''SSHFS'''
: SSH Filesystem or Secure SHell Filesystem is a file system client that may be used on operating systems for which an implementation of FUSE is available.
; '''toolchain'''
: Part of the SDK that contains ARM cross compilation tools, such as compiler and linker.
; '''UI'''
: User Interface.
; '''USB'''
: Universal Serial Bus is a specification to establish communication between devices and a host controller (usually personal computers).
; '''Valgrind'''
: A tool suite for debugging and profiling Linux programs.
; '''VNC'''
: Virtual Network Computing is a graphical desktop sharing system that uses the RFB protocol to remotely control another computer, transmitting the keyboard and mouse events from one computer to another and relaying the graphical screen updates back in the other direction, over a network.
; '''X11'''
: X Window System is a computer software system and network protocol that provides a GUI for networked computers.
; '''XML'''
: eXtensible Markup Language.
; '''ZeroConf'''
: Zero Configuration networking is a set of techniques that automatically creates a usable IP network without manual operator intervention or special configuration servers.

= Maemo Releases =

; '''Mistral'''
: Maemo 2.0 release for Nokia 770 device. Corresponds to the Nokia Internet Tablet SE 2006 version 2.01.2006.26-8.
; '''Scirocco'''
: Maemo 2.1 release for Nokia 770 device. Includs mainly bugfixes and some other enhancements. Corresponds to Nokia Internet Tablet SE 2006 version 2.2006.39-14.
; '''Gregale'''
: Maemo 2.2 release for Nokia 770 device (bugfixes and enhancements).
; '''Bora'''
: Maemo 3.x releases for Nokia N800 device. Corresponds to Internet Tablet OS releases "1.2006.47-20", "2.2006.51-6" (Maemo 3.0), "3.2007.10-7" (Maemo 3.1) and "4.2007.26-8"+"4.2007.38-2" (Maemo 3.2).
; '''Chinook'''
: Maemo 4.0.x releases for Nokia N800 and N810 devices. Corresponds to Internet Tablet OS releases "1.2007.44-4" (Maemo 4.0) and "2.2007.51-3" (Maemo 4.0.1)
; '''Diablo'''
: Maemo 4.1.x releases for Nokia N800, N810 and N810 WiMAX devices. Corresponds to Internet Tablet OS releases "4.2008.23-14" (Maemo 4.1), "4.2008.36-5" (Maemo 4.1.1) and "5.2008.43-7" (Maemo 4.1.2)
; '''Fremantle'''
: Maemo 5.x releases for N900 device. Corresponds to Maemo 5 OS release "1.2009.42-11" + eMMC content "1.2009.41-1" (Maemo 5) and OS release "2.2009.51-1" + eMMC content "1.2009.41-1" (Maemo 5 Update)
; '''Harmattan'''
: Maemo 6.x releases, corresponds to Maemo 6 OS release "x.2010.xx-x"

Documentation/Maemo PC Connectivity Tutorial/Configuration

2010-04-09T09:05:02Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Configuration =

= Connection Establishment =

On a Maemo device, connections can be easily configured using Maemo PC Connectivity applets. It is possible to configure a Maemo device to use USB, Bluetooth and WLAN connection types.

'''USB''' connection type sets a USB mode (Network, Mass Storage or Host) to be used between a Maemo device and a host PC.

'''Bluetooth''' connection type sets a Bluetooth network over TCP/IP between a Maemo device and a host PC.

'''WLAN''' connection type sets a WLAN ad-hoc network between a Maemo device and a host PC.

On the host PC side (Linux, Windows and Mac OS X), the Host PC Connectivity product provides some tools to make it easier to configure the chosen connection type between the Maemo device and the host PC. Next the configuration of each supported connection type (USB, Bluetooth and WLAN) between the Maemo device and host PC are described briefly.

== Configuring USB Network ==

For Maemo Diablo devices, the USB connection has been configured to '''Mass storage''' mode by default. That is, when connected to a host PC via USB cable, the Maemo device is visible as a memory card for the host PC.

For Fremantle, when a Maemo device is connected to the host PC via USB cable, the Maemo device shows a default pop-up menu where the USB mode can be selected. the choices given are '''Mass storage''' or '''PC Suite''' mode. You must NOT use this default USB pop-up menu if you have installed Maemo PC Connectivity to the N900 device! Just click outside this default USB pop-up menu to close it and use Maemo PC Connectivity widgets to change the USB mode.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' With the Maemo Fremantle platform and N900 device, if Maemo PC Connectivity has been installed, the USB connection is used in a different way beyond the default '''Mass storage''' and '''PC Suite''' modes and thus ONLY Maemo PC Connectivity applets can be used to change the USB mode for the Maemo N900 device.
|}

For '''USB''' connection type it is possible to set following options for a Maemo device:

; '''Network'''
: sets a USB network over TCP/IP between the Maemo device and host PC.
; '''Mass storage'''
: sets the Maemo device file system to be accessible from the host PC as a memory card.
; '''PC Suite'''
: sets the Maemo device to be accessible by Nokia applications like Nokia PC Suite.
; '''Host'''
: sets the Maemo device to USB Host mode, where it allows external USB devices (such as hard drives, digital cameras, card readers, input devices, and so on) to be connected to the Maemo device, just like to a regular PC.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Maemo Diablo N800 and N810 devices do not support PC Suite mode. Due to hardware limitations, Maemo Fremantle device N900 does not support USB Host mode.
|}

The description of how to setup a USB connection to Mass storage, PC Suite and Host modes is skipped, since the configuration is simply to select and apply the desired mode on a Maemo device using Maemo PC Connectivity. Next, it is explained how to configure a USB network over TCP/IP between a Maemo device and host PC through Maemo PC Connectivity. Before that, you must install the maemo-pc-connectivity meta package on the Maemo device and the host-pc-connectivity package on the host PC (Linux, Windows and Mac OS).

=== Configuring USB for Maemo devices ===

To set up a USB network for a Maemo device you need to start PC Connectivity Manager, figure [[#fig:pc_connectivity_mpc_nm_usb_basic|3.1]].

{| summary="PC Connectivity Manager"
|+ align="BOTTOM" |'''Figure 3.1:''' PC Connectivity Manager
|-
|
[[Image:mpc_maemo_nm_usb_basic.png|Image mpc_maemo_nm_usb_basic]]
|}

Follow these steps to enable USB Networking:

* Disconnect the USB cable from Maemo device
* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''
* Check '''USB''' option
* Press '''Apply''' button

* Connect the USB cable to the host PC.
* Press the '''Advanced''' button and PC Connectivity Manager switches to advanced mode, if you want to change the default values.
* Change network options such as DHCP Server, IP address, Gateway and Netmask.
* Click on the '''Apply''' button.

The USB Networking must have the following default values, figure [[#fig:pc_connectivity_mpc_nm_usb|3.2]].

{| summary="PC Connectivity Manager USB Networking"
|+ align="BOTTOM" |'''Figure 3.2:''' PC Connectivity Manager USB Networking
|-
|
[[Image:mpc_maemo_nm_usb.png|Image mpc_maemo_nm_usb]]
|}

* '''DHCP Server:''' enabled
* '''IP address:''' 192.168.2.15
* '''Gateway:''' 192.168.2.14
* '''Netmask:''' 255.255.255.0

Once you have configured your USB Network using PC Connectivity Manager, you can enable or disable it easily by using Connection Switcher from the status bar, figure [[#fig:pc_connectivity_mpc_switcher_usb|3.3]].

{| summary="Connection Switcher dialog"
|+ align="BOTTOM" |'''Figure 3.3:''' Connection Switcher dialog
|-
|
[[Image:mpc_maemo_switcher_usb.png|Image mpc_maemo_switcher_usb]]
|}

If you prefer, you can follow the steps below to configure USB Network manually for a Maemo device (Diablo):

* Run '''Utilities - X Terminal'''
* Type sudo gainroot
* Type insmod /mnt/initfs/lib/modules/2.6.21-omap1/g_ether.ko
* Edit the /etc/network/interfaces file to configure the IP address of the usb0 interface:

The /etc/network/interfaces file should have following entries in it:

auto usb0
iface usb0 inet static
address 192.168.2.15
netmask 255.255.255.0

* Type ifup usb0
* Plug in the USB cable

To disable USB Network manually on a Maemo device (Diablo), follow these steps:

* Run '''Utilities - X Terminal'''
* Type sudo gainroot
* Type ifdown usb0
* Type rmmod g_ether

=== Configuring USB for Linux ===

If you install the host-pc-connectivity package, your Linux host PC is ready for USB Network.

Otherwise, you can configure your Linux host PC manually following the steps below:

On Ubuntu, you need to edit the /etc/udev/rules.d/85-ifupdown.rules file and replace the following line:

SUBSYSTEM=="net", DRIVERS=="?*", GOTO="net_start"

with this line:

SUBSYSTEM=="net", GOTO="net_start"

If this workaround is not done, the usb0 interface does not get its IP address back when you unplug and plug back the Maemo device to the host PC. Therefore, you must restart the network manually with the command /etc/init.d/networking restart to get the usb0 IP address back. This is a known issue on Ubuntu (see the related bug report [https://bugs.launchpad.net/ubuntu/+source/ifupdown/+bug/130437 here]).

On Debian, this workaround is not needed.

Add the following lines to the network configuration file /etc/network/interfaces<nowiki>: </nowiki>

auto usb0
allow-hotplug usb0

mapping hotplug
script grep
map usb0

iface usb0 inet dhcp
up iptables -t nat -A POSTROUTING -s 192.168.2.15 -j MASQUERADE
up echo 1 > /proc/sys/net/ipv4/ip_forward
down iptables -t nat -D POSTROUTING -s 192.168.2.15 -j MASQUERADE
down echo 0 > /proc/sys/net/ipv4/ip_forward

You can now connect the USB cable. With this configuration, you ensure that the ifup usb0 command sets up the IP address correctly on the host PC since it is using DHCP. Also, it allows a Maemo device to access the Internet from the host PC through the usb0 interface.

If you are using VMware:

* Connect USB cable.
* Go to '''VMware - Devices - Netchip RNDIS/Ethernet Gadget''' and click on the '''Connect (Disconnect from host)''' option. If VMware hangs, unplug the USB cable and wait for a short period of time. You get two device in use error messages, one from Native OS and another from VMware (likely because of automatic USB Mass Storage mode).
* Connect the USB cable. Repeat the previous steps if any problems are encountered.

Invoke the sudo ifdown usb0 and sudo ifup usb0 commands. The down/up sequence ensures that the host PC attempts to reconnect the usb0 interface.

If this results in a lot of Failed to bring up usb0 errors, try again a few times. There can be a delay until the host PC and Maemo device become aware of each other. If it does not succeed but no error message is displayed, you can unplug and plug back the USB cable.

Test the usb0 connection with the following command ping 192.168.2.15

If you do not get the ping working, try again a few times. This can be an annoying process, especially in VMware where the USB connection may be automatically configured to Mass Storage mode every time you plug the USB cable into the host PC. It may even require restarting VMware in some cases.

=== Configuring USB for Windows ===

In order to get USB Networking funtioning between a Windows host PC and a Diablo Maemo device, you must replace the original Diablo kernel with a new one that fixes some generic Linux USB Networking issues.

To replace the Diablo kernel, follow these steps:

* Download the file diablo_kernel_usbnet_patch_windows_v0.4.zip from [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php Maemo Development Environment Downloads] page.
* Unzip the file.
* Replace the Diablo kernel by reflashing it using the flasher-3.5 application from the same [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php Maemo Development Environment Downloads] page.

$ flasher-3.5 -k diablo_kernel_usbnet_windows/zImage -f -R

Now, you can get USB Network working between a Diablo Maemo device and a Windows host PC.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' On Fremantle and the N900 device this kernel fix has already been applied by default.
|}

After reflashing the kernel to the Maemo Diablo device and installing the PC-Connectivity.exe package to the host PC, your Windows host PC is ready for USB Network. That is, Windows detects and configures the Maemo device automatically when you plug in the USB cable. Remember to activate USB Network on your Maemo device before plugging the cable into the Windows host PC.

If you did not enable the '''DHCP''' option for the Maemo device, you need to configure the USB Network address for the host PC through the application available on the Windows Start menu '''Start - Programs - PC-Connectivity - UsbNetworking''', figure [[#fig:pc_connectivity_mpc_win_usb_app|3.4]].

{| summary="USB Network address on Windows"
|+ align="BOTTOM" |'''Figure 3.4:''' USB Network address on Windows
|-
|
[[Image:mpc_win_usb_app.png|Image mpc_win_usb_app]]
|}

If you do not install the PC-Connectivity package, you have to configure the USB network manually on your Windows host PC. For that, you must follow the steps below:

* Activate USB Network on the Maemo device.
* Plug in the USB cable between the Maemo device and the Windows host PC.
* Windows detects the device.

In the '''Found New Hardware Wizard''', figure [[#fig:pc_connectivity_mpc_win_usb_device_found|3.5]], proceed as follows:

{| summary="Windows Found New Hardware Wizard"
|+ align="BOTTOM" |'''Figure 3.5:''' Windows Found New Hardware Wizard
|-
|
[[Image:mpc_win_usb_device_found.png|Image mpc_win_usb_device_found]]
|}

* Select the '''No, not this time''' option. Click on the '''Next''' button, figure [[#fig:pc_connectivity_mpc_win_usb_device_found|3.5]].
* Select the '''Install from a list or specific location (Advanced)''' option. Click on the '''Next''' button.
* Select the '''Don't search, I will choose the driver to install''' option.
* Click on the '''Next''' button, figure [[#fig:pc_connectivity_mpc_win_usb_choose_driver|3.6]].
* Select the '''Network adapters''' option. Click on the '''next''' button (optional screen).
* Select the '''Have disk''' option. Then, Click on the '''Browser''' button, select the driver (.inf file) and click on the '''OK''' button. The driver is available inside the zip file that was used to fix the Diablo kernel (diablo_kernel_usbnet_patch_windows_v0.4.zip).
* Follow the next steps as with a normal driver installation.

The new USB Network interface is available on the '''Start - Network Connections''' menu.

{| summary="Windows Search and Installation options for USB"
|+ align="BOTTOM" |'''Figure 3.6:''' Windows Search and Installation options for USB
|-
|
[[Image:mpc_win_usb_choose_driver.png|Image mpc_win_usb_choose_driver]]
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' If you did NOT choose the DHCP option on the Maemo device, you need to set up the network using the following information: IP address: 192.168.2.14 Subnet mask: 255.255.255.0, figure [[#fig:pc_connectivity_mpc_win_usb_tcp|3.7]].
|}

To check if the connection is working, go to Windows command prompt and type ping 192.168.2.15.

{| summary="Manual IP Network configuration dialog for USB"
|+ align="BOTTOM" |'''Figure 3.7:''' Manual IP Network configuration dialog for USB
|-
|
[[Image:mpc_win_usb_tcp.png|Image mpc_win_usb_tcp]]
|}

=== Configuring USB for Mac OS X ===

To enable USB Network to work on Mac OS X you can follow these steps:

* Activate USB network on the Maemo device.
* Plug in the USB cable between Maemo device and the Mac OS X host PC.
* The following pop-up should appear, figure [[#fig:pc_connectivity_mpc_mac_usb_pop_up|3.8]].
* Click on the '''Network Preferences''' button.
* Click on the '''Apply''' button. Now, you should be able to connect to your Maemo device.

{| summary="New network interface found pop-up dialog"
|+ align="BOTTOM" |'''Figure 3.8:''' New network interface found pop-up dialog
|-
|
[[Image:mpc_mac_usb_pop_up.png|Image mpc_mac_usb_pop_up]]
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' If you did not choose the DHCP option on the Maemo device, you need to set up the USB network address manually on '''Network panel'''. For example, IP address: 192.168.2.14 Subnet mask: 255.255.255.0, figure [[#fig:pc_connectivity_mpc_mac_usb_tcp_properties|3.9]].
|}

{| summary="Network panel configuration dialog"
|+ align="BOTTOM" |'''Figure 3.9:''' Network panel configuration dialog
|-
|
[[Image:mpc_mac_usb_tcp_properties.png|Image mpc_mac_usb_tcp_properties]]
|}

== Configuring Bluetooth Network ==

With Maemo PC Connectivity, you can configure a Bluetooth network between a Maemo device and a host PC by setting up connection attributes like IP address, network mask, and so on. For that, you have to first install Maemo PC Connectivity to the Maemo device and Host PC Connectivity to the host PC (Linux, Windows or Mac OS X).

=== Configuring Bluetooth for Maemo device ===

In order to set up a Bluetooth network for a Maemo device, you should follow these steps:

* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''.
* Click on the '''Advanced''' button.
* Select an environment or create a new one.
* Select the '''Bluetooth''' option as shown in Figure [[#fig:pc_connectivity_mpc_maemo_nm_bluetooth|3.10]].
* Click on '''Search''' to find the host PC.
* Once the host PC is found, mark its name and then click '''Select''', figure [[#fig:pc_connectivity_mpc_maemo_nm_bluetooth_search|3.11]].
* The default settings are presented below, you can change them if needed.
* Finally, click on '''Apply''' to enable the Bluetooth network.

{| summary="PC Connectivity Manager Bluetooth configuration"
|+ align="BOTTOM" |'''Figure 3.10:''' PC Connectivity Manager Bluetooth configuration
|-
|
[[Image:mpc_maemo_nm_bluetooth.png|Image mpc_maemo_nm_bluetooth]]
|}

Default values for Maemo device Bluetooth configuration are:

* '''DHCP Server:''' enabled
* '''IP address:''' 192.168.3.15
* '''Gateway:''' 192.168.3.14
* '''Netmask:''' 255.255.255.0
* '''Bluetooth address:''' empty (you should search the host PC to connect to), figure [[#fig:pc_connectivity_mpc_maemo_nm_bluetooth_search|3.11]].

{| summary="Searching Bluetooth devices dialog"
|+ align="BOTTOM" |'''Figure 3.11:''' Searching Bluetooth devices dialog
|-
|
[[Image:mpc_maemo_nm_bluetooth_search.png|Image mpc_maemo_nm_bluetooth_search]]
|}

Once you have configured your Bluetooth Network using PC Connectivity Manager, you can enable or disable it easily by using Connection Switcher from the status bar, figure [[#fig:pc_connectivity_mpc_maemo_switcher_bluetooth|3.12]].

{| summary="Connection Switcher dialog"
|+ align="BOTTOM" |'''Figure 3.12:''' Connection Switcher dialog
|-
|
[[Image:mpc_maemo_switcher_bluetooth.png|Image mpc_maemo_switcher_bluetooth]]
|}

=== Configuring Bluetooth for Linux ===

After you have installed the host-pc-connectivity package for your Linux host PC, it is ready for the Bluetooth network.

Or you can configure your Linux host PC manually for Bluetooth following the steps given below.

Add these lines to the file /etc/network/interfaces<nowiki>: </nowiki>

auto bnep0
iface bnep0 inet dhcp
up iptables -t nat -A POSTROUTING -s 192.168.3.15 -j MASQUERADE
up echo 1 > /proc/sys/net/ipv4/ip_forward
down iptables -t nat -D POSTROUTING -s 192.168.3.15 -j MASQUERADE
down echo 0 > /proc/sys/net/ipv4/ip_forward

Edit the file /etc/default/bluetooth and change these lines:

BLUETOOTH_ENABLED=1
...
PAND_ENABLED=1
...
PAND_OPTIONS="-listen -role=NAP -e bnep0"

Restart the Bluetooth service with the command:

$ sudo /etc/init.d/bluetooth restart

Now your Linux host PC is ready for the Bluetooth network.

=== Configuring Bluetooth for Windows ===

The description of how to configure Bluetooth on a Windows host PC is based on [http://www.bluesoleil.com/ the BlueSoleil application]. BlueSoleil is one of the most popular Windows Bluetooth applications. If you do not use BlueSoleil, the screenshots below can differ from what you see in your host PC, but they can help in understanding what you need to change on your Windows configuration.

You should follow the next steps to get the Bluetooth network configured in your Windows host PC (with BlueSoleil).

* In the '''System tray''', right click on the Bluetooth icon .
* Select the '''Bluetooth Configuration''' option, figure [[#fig:pc_connectivity_mpc_win_bluetooth_tray|3.13]].
* In the '''Bluetooth Configuration''' dialog, select the '''Accessibility''' tab.
* Check the '''Let other Bluetooth devices discover this computer''' option, figure [[#fig:pc_connectivity_mpc_win_bluetooth_accessibility|3.14]].
* In the '''Bluetooth Configuration''' dialog, select the '''Local Services''' tab.
* Mark the '''Network Access''' service and click the '''Properties...''' button, figure [[#fig:pc_connectivity_mpc_win_bluetooth_services|3.15]].
* If you want to share Internet over Bluetooth, select '''Allow other devices to access the Internet/LAN via this computer''' on the '''Select the type of the service to offer remote devices''' option.
* Click on the '''Configure Network Adapter''' button, figure [[#fig:pc_connectivity_mpc_win_bluetooth_properties|3.16]].
* Double click on the '''Internet Protocol (TCP/IP)''' option, figure [[#fig:pc_connectivity_mpc_win_bluetooth_network|3.17]].
* For all opened dialogs, press the '''OK''' button.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' If you did not choose the DHCP option on the Maemo device, type the following information for the network adapter: IP address: 192.168.3.14 Subnet mask: 255.255.255.0, figure [[#fig:pc_connectivity_mpc_win_bluetooth_tcp|3.18]]
|}

{| summary="Bluetooth configuration menu"
|+ align="BOTTOM" |'''Figure 3.13:''' Bluetooth configuration menu
|-
|
[[Image:mpc_win_bluetooth_tray.png|Image mpc_win_bluetooth_tray]]
|}

{| summary="Bluetooth Accessibility dialog"
|+ align="BOTTOM" |'''Figure 3.14:''' Bluetooth Accessibility dialog
|-
|
[[Image:mpc_win_bluetooth_accessibility.png|Image mpc_win_bluetooth_accessibility]]
|}

{| summary="Bluetooth Network Access entry"
|+ align="BOTTOM" |'''Figure 3.15:''' Bluetooth Network Access entry
|-
|
[[Image:mpc_win_bluetooth_services.png|Image mpc_win_bluetooth_services]]
|}

{| summary="Bluetooth Properties dialog"
|+ align="BOTTOM" |'''Figure 3.16:''' Bluetooth Properties dialog
|-
|
[[Image:mpc_win_bluetooth_properties.png|Image mpc_win_bluetooth_properties]]
|}

{| summary="Bluetooth Network properties dialog"
|+ align="BOTTOM" |'''Figure 3.17:''' Bluetooth Network properties dialog
|-
|
[[Image:mpc_win_bluetooth_network.png|Image mpc_win_bluetooth_network]]
|}

{| summary="Network Adapter configuration dialog"
|+ align="BOTTOM" |'''Figure 3.18:''' Network Adapter configuration dialog
|-
|
[[Image:mpc_win_bluetooth_tcp.png|Image mpc_win_bluetooth_tcp]]
|}

=== Configuring Bluetooth for Mac OS X ===

After installing the PC-Connectivity package to the host PC, your Mac OS X is ready for the Bluetooth network.

Otherwise, you can configure your Mac OS host PC manually by following these steps.

* Go to '''System Preferences''' and click on the '''Network''' icon, figure [[#fig:pc_connectivity_mpc_mac_bluetooth_network_preferences|3.19]].
* Add a new network interface, figure [[#fig:pc_connectivity_mpc_mac_bluetooth_network_add|3.20]].
* For the '''Interface''' field, select '''Bluetooth PAN''' type.
* For the '''Service Name''' field, write the interface name, figure [[#fig:pc_connectivity_mpc_mac_bluetooth_network_name|3.21]].
* Press the '''Apply''' button.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' If you did not choose the DHCP option on the Maemo device, select the newly created '''Bluetooth PAN''' interface and use the '''Manually''' option in the '''Configure''' field. After that, type the following information: IP address: 192.168.3.14 Subnet mask: 255.255.255.0, figure [[#fig:pc_connectivity_mpc_mac_bluetooth_network_tcp|3.22]]
|}

{| summary="System Preferences dialog"
|+ align="BOTTOM" |'''Figure 3.19:''' System Preferences dialog
|-
|
[[Image:mpc_mac_bluetooth_network_preferences.png|Image mpc_mac_bluetooth_network_preferences]]
|}

{| summary="Adding new network interface"
|+ align="BOTTOM" |'''Figure 3.20:''' Adding new network interface
|-
|
[[Image:mpc_mac_bluetooth_network_add.png|Image mpc_mac_bluetooth_network_add]]
|}

{| summary="Configuring new Bluetooth interface name"
|+ align="BOTTOM" |'''Figure 3.21:''' Configuring new Bluetooth interface name
|-
|
[[Image:mpc_mac_bluetooth_network_name.png|Image mpc_mac_bluetooth_network_name]]
|}

{| summary="Configuring Bluetooth interface network"
|+ align="BOTTOM" |'''Figure 3.22:''' Configuring Bluetooth interface network
|-
|
[[Image:mpc_mac_bluetooth_network_tcp.png|Image mpc_mac_bluetooth_network_tcp]]
|}

== Configuring a WLAN ad-hoc Network ==

With Maemo PC Connectivity, you can configure a WLAN ad-hoc network for your Maemo device. You can set up connection attributes such as IP address, network mask, and so on.

=== Configuring WLAN ad-hoc for a Maemo device ===

To set up a WLAN ad-hoc network for your Maemo device, you need to perform the following configuration steps.

In Control Panel, open the PC Connectivity Manager widget, figure [[#fig:pc_connectivity_mpc_maemo_nm_wlan_basic|3.23]].

{| summary="PC Connectivity Manager - basic mode"
|+ align="BOTTOM" |'''Figure 3.23:''' PC Connectivity Manager - basic mode
|-
|
[[Image:mpc_maemo_nm_wlan_basic.png|Image mpc_maemo_nm_wlan_basic]]
|}

Select the '''WLAN''' check-box and press the '''Apply''' button. A new WLAN ad-hoc connection is created with the following configuration:

* '''DHCP Server:''' Enabled
* '''IP Address:''' 192.168.4.14
* '''Gateway:''' 192.168.4.15
* '''Netmask:''' 255.255.255.0
* '''Essid:''' devel_adhoc
* '''WEP:''' key empty

If you want to change these default values, press the '''Advanced''' button, go to '''WLAN ad-hoc''' connection type and change the values. Then, press the '''Apply''' button, figure [[#fig:pc_connectivity_mpc_maemo_nm_wlan|3.24]].

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' By default, the WEP key is not used for new WLAN networks but for security reasons it is highly recommended to set also the wireless key.
|}

The WEP key must have 5, 10 or 13 characters (For example: aaaaa).

{| summary="PC Connectivity Manager - advanced mode"
|+ align="BOTTOM" |'''Figure 3.24:''' PC Connectivity Manager - advanced mode
|-
|
[[Image:mpc_maemo_nm_wlan.png|Image mpc_maemo_nm_wlan]]
|}

Once you have configured your WLAN ad-hoc Network using PC Connectivity Manager, you can enable or disable it easily using Connection Switcher from the status bar, figure [[#fig:pc_connectivity_mpc_maemo_switcher_wlan|3.25]].

{| summary="Connection Switcher dialog"
|+ align="BOTTOM" |'''Figure 3.25:''' Connection Switcher dialog
|-
|
[[Image:mpc_maemo_switcher_wlan.png|Image mpc_maemo_switcher_wlan]]
|}

=== Configuring WLAN ad-hoc for Linux ===

The iwconfig command is the configuration utility in Linux for WLAN interfaces. It is used to set the parameters of the network interface, which are specific to the wireless operation. The iwconfig command may also be used to display the parameters and the wireless network statistics. It extracts this information from the /proc/net/wireless file. By typing the iwconfig command without any arguments, it displays the current status of all wireless interfaces on the system.

To configure your host PC to connect with your Maemo device using a WLAN ad-hoc network, you should execute the following steps as root user:

$ ifconfig wlan0 up
$ iwconfig wlan0 mode Ad-Hoc
$ iwconfig wlan0 essid devel_adhoc
$ iwconfig wlan0 key off

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' The example below disables the usage of wireless key, but for security reasons it is highly recommended to set also the wireless key.
|}

To set the wireless key for your WLAN ad-hoc network, you should give the following command (using your own key value).

$ iwconfig wlan0 key 6161616161

You must use the same WEP key you used for Maemo device configuration, but as hexadecimal digits (for example, aaaaa is 6161616161 in hexadecimal).

=== Configuring WLAN ad-hoc for Windows ===

To set up a WLAN ad-hoc network that allows others computers to connect to your Windows host PC, follow these steps.

* Connect your Maemo device to devel_adhoc.
* In the '''System Tray''', right click on the wireless icon. Select the '''View Available Wireless Networks''' option, figure [[#fig:pc_connectivity_mpc_win_wlan_tray|3.26]].
* The '''Wireless Network Connection''' window displays the devel_adhoc network on the list. If you do not see devel_adhoc, click '''Refresh network list''' in the upper left corner, figure [[#fig:pc_connectivity_mpc_win_wlan_selection|3.27]].
* Select devel_adhoc, and then click on the '''Connect''' button.
* If you configured the '''WEP Key''' for your Maemo device, the Windows asks you to write that key at this point, figure [[#fig:pc_connectivity_mpc_win_wlan_key|3.28]].

{| summary="View Available Wireless Networks menu"
|+ align="BOTTOM" |'''Figure 3.26:''' View Available Wireless Networks menu
|-
|
[[Image:mpc_win_wlan_tray.png|Image mpc_win_wlan_tray]]
|}

{| summary="Choose a wireless network dialog"
|+ align="BOTTOM" |'''Figure 3.27:''' Choose a wireless network dialog
|-
|
[[Image:mpc_win_wlan_selection.png|Image mpc_win_wlan_selection]]
|}

{| summary="Wireless network key dialog"
|+ align="BOTTOM" |'''Figure 3.28:''' Wireless network key dialog
|-
|
[[Image:mpc_win_wlan_key.png|Image mpc_win_wlan_key]]
|}

=== Configuring WLAN ad-hoc for Mac OS X ===

To configure a WLAN ad-hoc network for your Mac OS X host PC, follow these steps.

* Connect your maemo device to devel_adhoc.
* On the '''Menu Bar''', click on the wireless icon and select the devel_adhoc network.
* If you configured '''WEP Key''' for your Maemo device, the Mac OS X asks you to write that key at this point.
* The wireless icon should change to inform that it is now connected.

= Using Configuration Environments =

With Maemo PC Connectivity, it is possible to use configuration environments for your Maemo device. For example, you can create an environment named Home that has the USB connection and the NFS disk mounts configured, and an environment named Office that has the WLAN connection and the SBRSH tool configured. When you are at home you can select a Home environment for your Maemo device and all previously stored connection and tool configurations in the Home environment are restored for your Maemo device.

To create or modify new configuration environments for your Maemo device you need to launch the Environment Manager widget, figure [[#fig:pc_connectivity_mpc_maemo_nm_env_create|3.29]].

{| summary="Environment Manager"
|+ align="BOTTOM" |'''Figure 3.29:''' Environment Manager
|-
|
[[Image:mpc_maemo_nm_env_create.png|Image mpc_maemo_nm_env_create]]
|}

To create a new environment you should follow these steps:

* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''.
* Click on the '''Advanced''' button.
* Click on the '''...''' button.
* Click on the '''New''' button.
* Set the environment name. For example, '''Home''', and click on the '''Ok''' button.
* Configure connections and tools to be used with this environment. For example, USB connection and NFS tool.
* Click on the '''Save''' button.

After you have created new environments, you can switch between them using the Connection Switcher widget, figure [[#fig:pc_connectivity_mpc_maemo_switcher_env|3.30]].

{| summary="Connection Switcher"
|+ align="BOTTOM" |'''Figure 3.30:''' Connection Switcher
|-
|
[[Image:mpc_maemo_switcher_env.png|Image mpc_maemo_switcher_env]]
|}

To change between stored environments using Connection Switcher:

* Run Connection Switcher from the status bar.
* Select an environment.

All stored configuration information for the chosen environment are applied to the Maemo device.

Also, the PC Connectivity Manager widget can be used to switch between stored environments, figure [[#fig:pc_connectivity_mpc_maemo_nm_env_basic|3.31]].

{| summary="PC Connectivity Manager - Basic mode"
|+ align="BOTTOM" |'''Figure 3.31:''' PC Connectivity Manager - Basic mode
|-
|
[[Image:mpc_maemo_nm_env_basic.png|Image mpc_maemo_nm_env_basic]]
|}

* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''.
* Select an environment.
* Click on the '''Apply''' button.

You can modify stored configuration environments with the PC Connectivity Manager widget in its '''Advanced''' mode, figure [[#fig:pc_connectivity_mpc_maemo_nm_env_advanced|3.32]].

{| summary="PC Connectivity Manager - Advanced mode"
|+ align="BOTTOM" |'''Figure 3.32:''' PC Connectivity Manager - Advanced mode
|-
|
[[Image:mpc_maemo_nm_env.png|Image mpc_maemo_nm_env]]
|}

* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''.
* Click on the '''Advanced''' button.
* Change the environment configuration. For example, USB connection and/or X11VNC tool.
* Click on the '''Apply''' button. All configurations, including changes, are saved and applieds

Documentation/Maemo PC Connectivity Tutorial/File Sharing

2010-04-09T09:05:01Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= File Sharing =

= Disk mounting =

Maemo PC Connectivity provides some tools for easily sharing files between a Maemo device and a host PC. You can can mount the file system of a Maemo device to the host PC over a network and interact with it as it is a local disk. Also, it is possible to mount a file system of a host PC to the Maemo device. For that, you have to install Maemo PC Connectivity on the Maemo device and Host PC Connectivity on the host PC (Linux, Windows and Mac OS X).

This chapter describes how to use the disk mounting tools available with Maemo PC Connectivity. To simplify the process, it is assumed that you already have a working USB network between your Maemo device and the host PC.

The recommended tools and methods to mount the file system of a Maemo device to a host PC are listed in table 6.1.

{| border="1" cellpadding="3"
|+ '''Table 6.1:''' Recommended mount tools for PC
|-
| align="CENTER" |
| align="CENTER" | Linux
| align="CENTER" | Windows
| align="CENTER" | Mac OS
|-
| align="CENTER" | SSHFS
| align="CENTER" | X
| align="CENTER" |
| align="CENTER" | X
|-
| align="CENTER" | NFS
| align="CENTER" | X
| align="CENTER" |
| align="CENTER" | X
|-
| align="CENTER" | SAMBA
| align="CENTER" | X
| align="CENTER" | X
| align="CENTER" | X
|}

The recommended tools and methods to mount the file system of a host PC to a Maemo device are listed in table 6.2.

{| border="1" cellpadding="3"
|+ '''Table 6.2:''' Recommended mount tools for Maemo device
|-
| align="CENTER" |
| align="CENTER" | Linux
| align="CENTER" | Windows
| align="CENTER" | Mac OS
|-
| align="CENTER" | SSHFS
| align="CENTER" | X
| align="CENTER" |
| align="CENTER" | X
|-
| align="CENTER" | NFS
| align="CENTER" | X
| align="CENTER" |
| align="CENTER" |
|-
| align="CENTER" | SAMBA
| align="CENTER" | X
| align="CENTER" | X
| align="CENTER" | X
|}

On the host PC, you must type the commands below in the terminal on Linux and Mac OS X and in the Cygwin command shell on Windows.

== Using SSHFS mounts ==

SSHFS (SSH File System) is a file system client based on the SSH protocol. It allows users to mount locally a remote file system via SSH. With SSHFS, you can remotely access the Maemo device file system from the host PC and vice versa.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' SSHFS mounts do not work on Windows host PC.
|}

If you want to mount the Maemo device file system to your host PC, you can execute the following commands.

$ mkdir ~/maemo
$ sshfs user@192.168.2.15:/ ~/maemo -o rw,nonempty
user@192.168.2.15's password: <type user password here>

If you did not set the SSH password for user yet, you can use the root account. You should set up the password for the user account by following these steps:

$ ssh root@192.168.2.15
root@192.168.2.15's password: <type root password here>
Nokia-810:~# passwd user
Changing password for user
Enter the new password (minimum of 5, maximum of 8 characters)
Please use a combination of upper and lower case letters and numbers.
New password: <type new user password here>
Re-enter new password: <retype user password>
Password changed

If you want to mount the host PC file system to your Maemo device, you can execute the following commands:

$ mkdir ~/hostpc
$ sshfs <host_pc_user>@<host_pc_ip>:/ ~/hostpc -o rw,nonempty
<host_pc_user>@<host_pc_ip>'s password: <type user password here>

As SSHFS is a user mode file system, you cannot use the standard Linux mount command directly. For example, you should execute the following command to unmount the Maemo device file system from the host PC.

$ fusermount -u ~/maemo

You can configure SSH to use keys and not to ask for a password every time by exchanging the SSH keys as described in the SSH installation chapter.

== Using NFS mounts ==

With NFS (Network File System), you can share folders from your Maemo device or host PC over a network. Below are instructions on how to share a folder from a Maemo device using NFS.

=== Configuring NFS for Maemo device ===

You should follow these steps to share a folder from your Maemo device through NFS using Maemo PC Connectivity configuration widget:

* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''.
* Click on the '''Advanced''' button.
* Go to the '''Tool Manager''' tab.
* Select the '''NFS''' option. After that, change the options according to your needs, figure [[#fig:pc_connectivity_mpc_maemo_nm_nfs|6.1]].
* Click on the '''Exported Paths''' button. Then add the folders to be shared, figure [[#fig:pc_connectivity_mpc_maemo_nm_nfs_folders|6.2]].
* Click on the '''Allowed IPs''' button. Then add the host PC's IP addresses that are allowed to access the shared folders, figure [[#fig:pc_connectivity_mpc_maemo_nm_nfs_ips|6.3]].

{| summary="PC Connectivity Manager - NFS option"
|+ align="BOTTOM" |'''Figure 6.1:''' PC Connectivity Manager - NFS option
|-
|
[[Image:mpc_maemo_nm_nfs.png|Image mpc_maemo_nm_nfs]]
|}

{| summary="PC Connectivity Manager - Shared folders list"
|+ align="BOTTOM" |'''Figure 6.2:''' PC Connectivity Manager - Shared folders list
|-
|
[[Image:mpc_maemo_nm_nfs_folders.png|Image mpc_maemo_nm_nfs_folders]]
|}

{| summary="PC Connectivity Manager - Allowed IPs list"
|+ align="BOTTOM" |'''Figure 6.3:''' PC Connectivity Manager - Allowed IPs list
|-
|
[[Image:mpc_maemo_nm_nfs_ips.png|Image mpc_maemo_nm_nfs_ips]]
|}

If you want, you can share a folder from your Maemo device manually. The following steps describe how to share the folder (/home/user/MyDocs) from a Maemo device over a network by giving access to the host PC IP address (192.168.2.14).

Connect to the Maemo device via SSH. Edit the file /etc/exports and add the folder you want to share and set the permissions of your shares (IP addresses).

/home/user/MyDocs 192.168.2.14(rw,no_root_squash,async,no_subtree_check)

Next restart the User Mode NFS server:

$ /etc/init.d/unfs3 restart

=== Configuring NFS for host PC ===

You must follows these steps to share a folder from a host PC over a network and giving access to it for Maemo device's IP address (192.168.2.15):

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' NFS mounts do not work on Windows host PC.
|}

Edit the file /etc/exports and add the folder you want to share and set the permissions for your shares (IP addresses).

/home/<host_pc_user> 192.168.2.15(rw,no_root_squash,async,no_subtree_check)

Next restart the User Mode NFS server:

$ sudo /etc/init.d/unfs3 restart

=== Accessing NFS shares with Maemo device ===

Once you configured NFS on your Maemo device, you can access the shared folders from your host PC over the network. Below are instructions on how to access the shared NFS folders from the Linux host PC.

On the host PC, run the showmount command to check if NFS sharing is working.

$ showmount -e <device_ip>
Export list for 192.168.2.15:
/home/user/MyDocs 192.168.2.14

Next mount the exported Maemo device folder from the host PC.

$ mkdir /tmp/MyDocs
$ sudo mount -t nfs <device_ip>:/home/user/MyDocs /tmp/MyDocs

You can unmount the same folder with the following command:

$ sudo umount /tmp/MyDocs

=== Accessing NFS shares with Host PC ===

Once you have configured NFS on your host PC, you can access the shared folders from your Maemo device over a network. Below are instructions on how to access the shared NFS folders from your Maemo device.

On the Maemo device mount the shared host PC folder.

$ mkdir ~/hostpc
$ mount -t nfs <host_pc_ip>:/home/<host_pc_user> ~/hostpc

You can unmount the same folder with the following command:

$ sudo umount ~/hostpc

== Using Samba mounts ==

Samba allows file sharing between computers over the network. With Samba, you can remotely access the Maemo device file system from the host PC and vice versa. Once you have shared your file system through Samba, it is available every time you reconnect to the network.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Samba does not work on Maemo Fremantle devices such as N900 but works fine with Maemo Diablo devices such as N800 and N810.
|}

=== Configuring Samba for Maemo device ===

To be able to share a folder from your Maemo device, you should follow these steps.

* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''.
* Click on the '''Advanced''' button.
* Go to the '''Tool Manager''' tab.
* Select the '''Samba''' option. After that, change the options according to your needs (Workgroup, User and Password), figure [[#fig:pc_connectivity_mpc_maemo_nm_samba|6.4]].
* Click on the '''Exported Paths''' button. Then add the folders to be shared, figure [[#fig:pc_connectivity_mpc_maemo_nm_samba_paths|6.5]].
* Click on the '''Apply''' button.

{| summary="PC Connectivity Manager - Samba options"
|+ align="BOTTOM" |'''Figure 6.4:''' PC Connectivity Manager - Samba options
|-
|
[[Image:mpc_maemo_nm_samba.png|Image mpc_maemo_nm_samba]]
|}

{| summary="PC Connectivity Manager - Samba shared folders"
|+ align="BOTTOM" |'''Figure 6.5:''' PC Connectivity Manager - Samba shared folders
|-
|
[[Image:mpc_maemo_nm_samba_paths.png|Image mpc_maemo_nm_samba_paths]]
|}

You can access your host PC shared folders from your Maemo device.

* Open the '''Utilities - File Manager''' application.
* Click on the '''Shared folders''' option, figure [[#fig:pc_connectivity_mpc_maemo_nm_samba_access|6.6]].
* Select the desired shared folder.

{| summary="PC Connectivity Manager - Shared folders dialog"
|+ align="BOTTOM" |'''Figure 6.6:''' PC Connectivity Manager - Shared folders dialog
|-
|
[[Image:mpc_maemo_nm_samba_access.png|Image mpc_maemo_nm_samba_access]]
|}

=== Configuring Samba for Linux ===

To be able to share a folder from your Linux host PC, you should follow these steps:

* Open the File Manager ('''Nautilus''').
* Right click the folder you want to share, and select '''Sharing options'''.
* Type the '''Share name''' and check the '''Guest access''' option, figure [[#fig:pc_connectivity_mpc_linux_ubuntu_samba_share|6.7]].
* Click on the '''Create share''' button.

{| summary="Linux folder sharing"
|+ align="BOTTOM" |'''Figure 6.7:''' Linux folder sharing
|-
|
[[Image:mpc_linux_ubuntu_samba_share.png|Image mpc_linux_ubuntu_samba_share]]
|}

If Samba is not installed, Ubuntu requests the installation at this point. Otherwise, you can install Samba manually.

$ sudo apt-get install samba

To access a shared folder from the Maemo device using your Windows host PC.

* Open the File Manager (Nautilus) and type: smb://<maemo_device_ip>, figure [[#fig:pc_connectivity_mpc_linux_ubuntu_samba_access|6.8]].
* Press '''Enter'''.

{| summary="Accessing shared folder with Final Manager"
|+ align="BOTTOM" |'''Figure 6.8:''' Accessing shared folder with Final Manager
|-
|
[[Image:mpc_linux_ubuntu_samba_access.png|Image mpc_linux_ubuntu_samba_access]]
|}

=== Configuring Samba for Windows ===

To be able to share a folder from your Windows host PC, you should follow these steps.

* Open the File Manager ('''Windows Explorer''').
* Right click the appropriate folder, and then click Sharing.
* In the folder's properties, click '''Share this folder'''. Use the default name for the share.
* Click the '''Permissions''' button to change permissions according to your needs.

To access a folder shared from your Maemo device, you need to do the following on your Windows host PC:

* Click '''Start''', and then click '''Run'''.
* Type your Maemo device IP address as follows: <maemo_device_ip>.
* The shared folders of your Maemo device are shown.

=== Configuring Samba for Mac OS X ===

To be able to share a folder from your Mac OS X host PC, you should follow these steps:

* Go to '''System Preferences''' and click on the '''Sharing''' icon.
* Select the '''File Sharing''' service.
* Add a folder you want to share, and then set the permissions for it, figure [[#fig:pc_connectivity_mpc_mac_samba_share|6.9]].

{| summary="Mac OS X Sharing dialog"
|+ align="BOTTOM" |'''Figure 6.9:''' Mac OS X Sharing dialog
|-
|
[[Image:mpc_mac_samba_share.png|Image mpc_mac_samba_share]]
|}

To access a folder shared from a Maemo device you need to do following on your Mac OS X host PC.

* Go to the File Manager application ('''Finder''').
* With the '''Finder''' open, click on the '''Go''' menu and select the '''Connect to Server''' option.
* Type your Maemo device IP address as follows: smb://<maemo_device_ip>, figure [[#fig:pc_connectivity_mpc_mac_samba_access|6.10]].
* Click on the '''Connect''' button.

{| summary="Mac OS X connect to server dialog"
|+ align="BOTTOM" |'''Figure 6.10:''' Mac OS X connect to server dialog
|-
|
[[Image:mpc_mac_samba_access.png|Image mpc_mac_samba_access]]
|}

= File transfer =

You have several different ways to transfer files between a Maemo device and a host PC using tools provided by Maemo PC Connectivity. First, you have to install Maemo PC Connectivity to the Maemo device and Host PC Connectivity to the host PC (Linux, Windows and Mac OS X). Below describes how to use specific file transfer tools available from the Maemo PC Connectivity product. To simplify the process, it has been assumed that you already have a working USB network configured between the Maemo device and host PC.

On the host PC, you must type the commands below using terminal on Linux and Mac OS and using Cygwin command shell on Windows.

== Using SCP ==

With SCP (Secure Copy), you can securely transfer files between a local and a remote host or between two remote hosts, using the SSH protocol. Below describes in detail how to transfer files between the Maemo device and host PC using SCP.

You should follow the SCP command examples below to transfer files from a local to a remote host:

$ scp <source_file> <user>@<host_name>:<path>/<target_file>

For example, if you want to transfer a file called file.txt from a host PC to a Maemo device, you should use this command on the host PC:

$ scp file.txt root@192.168.2.15:/etc/file.txt

You should follow this SCP command example to transfer files from a remote to a local host:

$ scp <user>@<host_name>:<path>/<source_file> <target_file>

For example, if you want to transfer a file called file.txt from a Maemo device to a host PC, you should use this command on host PC:

$ scp root@192.168.2.15:/etc/file.txt file.txt

You can use ssh-key-exchange as described in the SSH installation chapter to avoid SSH requiring a password every time.

== Using SFTP ==

After Maemo PC Connectivity has been installed to the Maemo device, your Maemo device folders can be accessed from a host PC using the SFTP client. If you also installed Host PC Connectivity your host PC already has a GUI-based SFTP client, FileZilla, installed. Therefore to access your Maemo device folders from the host PC through SFTP, simply follow these steps.

Run the FileZilla client, figure [[#fig:pc_connectivity_mpc_sftp|6.11]].

* Linux - Ubuntu: '''Applications - Internet - FileZilla FTP Client'''.
* Windows: '''Start - Programs - FileZilla FTP Client - FileZilla'''.
* Mac OS: '''/Applications/FileZilla'''.

{| summary="FileZilla FTP Client"
|+ align="BOTTOM" |'''Figure 6.11:''' FileZilla FTP Client
|-
|
[[Image:mpc_sftp.png|Image mpc_sftp]]
|}

* Type the IP address of your Maemo device in the '''Host''' field.
* Type your '''Username''' and '''Password''' to set up the SSH connection on your Maemo device and type 22 (for SSH) in the '''Port''' field.
* Click on the '''Quickconnect''' button. Your Maemo device folders will appear in the '''Remote Site''' area.

== Using Rsync ==

As Maemo PC Connectivity and Host PC Connectivity products installs Rsync for your environment, you can incrementally transfer files and directories between a Maemo device and a host PC. You can send and receive files in such a way that only the changed bytes inside files are copied between the Maemo device and the host PC. Rsync also removes files from target folders if those files were deleted from the source folders in order to keep both folders in sync. You can find usage examples and documentation about Rsync from the [http://rsync.samba.org/ Rsync web page].

Rsync is a much more powerful tool than standard SCP, SFTP or disk mounts to back up or synchronise large files (such as music, pictures, maps and movies) between a Maemo device and a host PC.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Rsync protocol is also used by several backup and file synchronisation services available from the Internet.
|}

Documentation/Maemo PC Connectivity Tutorial/Remote Access

2010-04-09T09:05:00Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Remote Access =

= Remote desktop =

Maemo PC Connectivity provides tools to access the desktop of a remote machine from a local machine over the network. That is, you can have the desktop GUI of your Maemo device displayed on your host PC and vice-versa. For that, you need to install Maemo PC Connectivity on the Maemo device and Host PC Connectivity on the host PC (Linux, Windows and Mac OS X). This chapter describes how to use these remote desktop tools. For simplicity, it is assumed that you already have a USB network working between the Maemo device and the host PC.

== Using X11VNC ==

With the X11VNC server, it is possible to share the GUI (Graphical User Interface) of your Maemo device with your host PC. That is, you can access the desktop of your Maemo device remotely from the host PC as you are physically using it. Below is described how to configure your Maemo device and host PC for X11VNC access.

=== Configuring X11VNC for Maemo ===

If you installed Maemo PC Connectivity, your Maemo device already has a X11VNC server installed.

You can configure the X11VNC server through the PC Connectivity Manager applet, as described below.

* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''.
* Click on the '''Advanced''' button.
* Select the '''Tool Manager''' tab.
* Now you can enable and disable the X11VNC server, change the UDP port and set the loop mode, figure [[#fig:pc_connectivity_mpc_maemo_nm_x11vnc|5.3]].
* Click on the '''Apply''' button.

{| summary="PC Connectivity Manager - X11VNC tool"
|+ align="BOTTOM" |'''Figure 5.3:''' PC Connectivity Manager - X11VNC tool
|-
|
[[Image:mpc_maemo_nm_x11vnc.png|Image mpc_maemo_nm_x11vnc]]
|}

As the X11VNC server is not launched automatically when you turn the Maemo device on, you need to start it manually. You can use the PC Connectivity Manager wizard or start X11VNC as any third-party application from the installed application list.

=== Configuring X11VNC for Linux ===

If you installed Host PC Connectivity, your Linux host PC already has a VNC client called TightVNC Viewer. Otherwise, you should install the VNC client manually from [http://www.tightvnc.com/download.php TightVNC download] page.

$ sudo apt-get install xtightvncviewer

You can access your Maemo device through the TightVNC Viewer application by giving the Maemo device IP address.

$ xtightvncviewer 192.168.2.15

=== Configuring X11VNC for Windows ===

If you installed Host PC Connectivity, your Windows host PC already has a VNC client called TightVNC Viewer. Otherwise, you can download and install TightVNC manually from [http://www.tightvnc.com/download.php TightVNC download] page.

You can access your Maemo device through the TightVNC Viewer application by giving the Maemo device IP address.

* Run '''Start - Programs - TightVNC - TigthtVNC Viewer''', figure [[#fig:pc_connectivity_mpc_win_vnc_ip|5.4]].
* Type the IP address of your Maemo device and press the '''Connect''' button.

{| summary="TightVNC connection dialog"
|+ align="BOTTOM" |'''Figure 5.4:''' TightVNC connection dialog
|-
|
[[Image:mpc_win_vnc_ip.png|Image mpc_win_vnc_ip]]
|}

Now you should see the desktop of your Maemo device on the host PC screen, figure [[#fig:pc_connectivity_mpc_win_vnc_desktop|5.5]].

{| summary="TightVNC remote desktop on Windows"
|+ align="BOTTOM" |'''Figure 5.5:''' TightVNC remote desktop on Windows
|-
|
[[Image:mpc_win_vnc_desktop.png|Image mpc_win_vnc_desktop]]
|}

=== Configuring X11VNC for Mac OS X ===

If you installed Host PC Connectivity, your Windows host PC already has a VNC client called TightVNC Viewer. Otherwise, you can download and install TightVNC Java version manually from [http://www.tightvnc.com/download.php TightVNC download] page.

* Download the TightVNC Java version.
* Create a new folder and uncompress the zip file.

$ mkdir ~/tightvnc
$ mv tightvnc-1.3.10_javabin.tar.gz ~/tightvnc
$ cd ~/tightvnc
$ tar -zxvf tightvnc-1.3.10_javabin.tar.gz

You can access your Maemo device through the TightVNC Viewer application by giving the Maemo device IP address.

$ java VncViewer HOST 192.168.2.15 PORT 5900

Now, you should see the desktop of your Maemo device on the host PC screen, figure [[#fig:pc_connectivity_mpc_mac_vnc_desktop|5.6]].

{| summary="TightVNC remote desktop on Mac OS X"
|+ align="BOTTOM" |'''Figure 5.6:''' TightVNC remote desktop on Mac OS X
|-
|
[[Image:mpc_mac_vnc_desktop.png|Image mpc_mac_vnc_desktop]]
|}

=== Troubleshooting X11VNC ===

The current X11VNC server (0.9.3-maemo4) available for Maemo Diablo devices may crash if a key is pressed on the host PC keyboard and there is no mapping for that key on the Maemo device. A workaround is to manually add missing key mappings as described below.

You should install the xev application to the host PC to trace the key codes, which crash the Maemo device.

Here is how to install xev to the Linux host PC.

$ sudo apt-get install x11-utils

Execute the xev application on the host PC.

$ xev

Type the key on the host PC that crashes the Maemo device. You get something like this on xev output.

KeyPress event, serial 31, synthetic NO, window 0x2000001,
root 0x3f, subw 0x0, time 2488134890, (-257,171), root:(294,445),
state 0x10, keycode 48 (keysym 0xfe51, dead_acute), same_screen YES,
XLookupString gives 2 bytes: (c2 b4) "'"
XmbLookupString gives 0 bytes:
XFilterEvent returns: True

Get the key code name. In this example, it is dead_acute. On the Maemo Diablo device, map this key to '''None''' in the /usr/share/applications/hildon/x11vnc.desktop file. Add the key mapping for '''dead_acute-None''' as described below.

Exec=/usr/bin/x11vnc -display :0 -nowf -noxdamage -noscr -remap dead_acute-None,<key_name_1>-None,<key_name_N>-None

On your Maemo Diablo device, restart X11VNC server and check if the problem got fixed.

== Using Rdesktop ==

Rdesktop is a client to access remotely your Windows host PC from your Maemo device. Below are instructions on how to enable Rdesktop access for your Windows host PC and how to use the Rdesktop client on your Maemo device to access the desktop of your Windows host PC.

=== Configuring Rdesktop for Windows ===

You must enable the '''Remote Desktop''' feature on your Windows host PC so that you can control it remotely from your Maemo device. For that, you must be logged on as an administrator or as a member of the Administrators group for your Windows PC to enable the Remote Desktop feature.

To set up your Windows host PC for Rdesktop access:

* Click '''Start''', point to '''Settings''', click '''Control Panel''', and then double-click the '''System''' icon.
* On the '''Remote''' tab, select the '''Allow users to connect remotely to this computer''' check-box, figure [[#fig:pc_connectivity_mpc_win_rdesktop|5.7]].
* Ensure that you have the proper permissions to connect to your host PC remotely. For that, click the '''Select Remote Users...''' button to give access to your user account.
* Click the '''OK''' button.
* Leave your host PC running and connected to the network with Internet access.

{| summary="Windows Remote Access configuration"
|+ align="BOTTOM" |'''Figure 5.7:''' Windows Remote Access configuration
|-
|
[[Image:mpc_win_rdesktop.png|Image mpc_win_rdesktop]]
|}

If you are running Windows XP Service Pack 2 and you enable Remote Desktop, Windows Firewall is automatically configured to allow Remote Desktop connections to your host PC. However, Remote Desktop does not work if you have Windows Firewall configured to allow no exceptions. To allow exceptions in Windows Firewall, open '''Security Center''' from the '''Control Panel''', click '''Windows Firewall''' and clear the check-box next to '''Don't allow exceptions'''.

=== Configuring Rdesktop for Maemo device ===

If you installed Maemo PC Connectivity, your Maemo device already has a Rdesktop client installed.

Open '''Utilities - X Terminal''' and execute Rdesktop application.

$ rdesktop-cli -u <windows_user> -p <windows_password> <windows_ip_address>

You must pass your user name and password to access the given Windows host PC.

Now, you should see the desktop of your Windows host PC on your Maemo device screen.

== Using X Tunneling ==

With X Tunneling, it is possible to execute an application on your Maemo device and display its GUI on your host PC screen and vice versa using an SSH connection. Below are instructions on how to configure X11 tunneling between the Maemo device and Linux and Max OS X host PC.

You should follow these steps to display the GUI of your Maemo device on your host PC. These instructions work with Linux and Mac OS X host PCs.

On Linux and Mac OS X host PCs:

$ Xephyr :3 -ac -dpi 96 -screen 800x480x16 -host-cursor &
$ ssh -l <maemo_device_user> -R 6002:<host_pc_ip>:6003 <maemo_device_ip>
$ export DISPLAY=:2
$ /usr/lib/sapwood/sapwood-server &
$ <run_application>

You should follow these steps to display the GUI of your Linux host PC on your Maemo device. These instructions work only with Linux host PCs.

On a Maemo device:

$ ssh -l <host_pc_user> -R 6000:<maemo_device_ip>:6000 -X <host_pc_ip>
$ <run_application>

Documentation/Maemo PC Connectivity Tutorial/Introduction

2010-04-09T09:05:00Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Introduction =

The Maemo PC Connectivity project aims to make easier communication between a Maemo device and a host PC. For this, it provides a set of tools to simplify tasks like connection establishment, connection sharing, remote access, file sharing and transfer.

Maemo PC Connectivity fully supports the Maemo Fremantle platform and devices (such as N900) and the Maemo Diablo platform and devices (such as N800 and N810).

{| summary="Maemo device - N900"
|+ align="BOTTOM" |'''Figure 1.1:''' Maemo device - N900
|-
|
[[Image:Nokia_N900_48.png|Image Nokia_N900_48]]
|}

Maemo PC Connectivity target users are Maemo developers as they must use it to set up their Maemo development environment. The Maemo development environment consists of a Maemo device and host PC running Scratchbox and Maemo SDK (and possibly Eclipse IDE) integrated together with services provided by Maemo PC Connectivity. Maemo PC Connectivity is targeted also for those non-developers who are able to use provided tools and services from command line interfaces, as all services available do not yet have a simple enough Graphical User Interface for end users.

Maemo PC Connectivity supports USB Networking, Bluetooth and WLAN connectitivy types between a Maemo device and a remote machine. USB Networking is recommended as, performance wise, it provides the best connectivity for networking. All services that Maemo PC Connectivity provides can be used with all connectivity types assuming that the host PC accessing services has the required clients available.

Some basic services provided by Maemo PC Connectivity and Host PC Connectivity to integrate a Maemo device and host PC include:

; '''Connection establishment'''
: By using Maemo PC Connectivity configuration applets, it is possible to easily establish a connection over USB, Bluetooth or WLAN, and to configure services between a Maemo device and a host PC.
; '''Connection sharing'''
: By using Maemo PC Connectivity applets and services installed to the Maemo device, it is possible to easily share connection over USB, Bluetooth or WLAN both ways, that is from a Maemo device to a host PC or from a host PC to a Maemo device.
; '''Secure Shell'''
: SSH allows data to be exchanged using a secure channel between two networked devices.
; '''Scratchbox Remote Shell'''
: SBRSH is a remote command execution system similar to rsh and ssh. It is designed with slow devices and Scratchbox's special requirements in mind.
; '''SSH File System'''
: SSHFS is a file system client based on the SSHprotocol. It allows local mounting of a remote file system via SSH.
; '''Network File System'''
: NFS allows file system sharing over a network.
; '''Samba'''
: provides shared access to files, printers, serial ports, and miscellaneous communications between nodes on a network. Most usage of Samba involves host PCs running Microsoft Windows.
; '''Virtual Network Computing'''
: VNC is a graphical desktop sharing system that allows a host PC to remotely control a Maemo device.
; '''Rdesktop'''
: is a client for remotely accessing Windows desktops from a Maemo device.
; '''X Tunneling over SSH'''
: allows the forwarding of X11 desktop from a Maemo device to a host PC.
; '''SSH File Transfer Protocol'''
: SFTP is a network protocol that provides a secure file transfer over a network using SSH.
; '''Secure Copy'''
: SCP is another way to transfer files between a local and a remote host using SSH.
; '''Rsync'''
: is a utility that provides fast incremental file transfer, that is, it transfers only the bytes inside files that have been changed since the previous transfer.

----

Documentation/Maemo PC Connectivity Tutorial/Network Sharing

2010-04-09T09:04:59Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Network Sharing =

With Maemo PC Connectivity, you can easily set up an Internet connection and share it from a Maemo device to a host PC or from a host PC to a Maemo device. For sharing a connection from a Maemo device to a host PC, you should configure from which interface (WLAN, USB or Bluetooth) the Maemo device accesses the Internet and share it with other interfaces (WLAN, USB and/or Bluetooth).

= Sharing network from Maemo device =

To share a network connection from a Maemo device to a host PC you need perform these steps on the Maemo device:

* Run '''Settings - Control Panel - Connectivity - PC Connectivity Manager'''.
* Click on the '''Advanced''' button.
* Select the '''Internet''' connection type, figure [[#fig:pc_connectivity_network_sharing_mpc_maemo_nm_internet_sharing|4.1]].
* With the '''Connect Using''' option, you can choose from which interface (WLAN, WLAN adhoc, USB or Bluetooth) the Maemo device accesses the network.
* With the '''Share internet connection with''' option, you can choose the interfaces (WLAN, USB and/or Bluetooth) with which to share the Internet.
* Click on the '''Apply''' button.

{| summary="PC Connectivity Manager - Internet Sharing"
|+ align="BOTTOM" |'''Figure 4.1:''' PC Connectivity Manager - Internet Sharing
|-
|
[[Image:mpc_maemo_nm_internet_sharing.png|Image mpc_maemo_nm_internet_sharing]]
|}

= Sharing network from Linux =

After you have installed the host-pc-connectivity package to your Linux host PC, you can automatically share an Internet network connection from your Linux host PC to a Maemo device.

If you want, you can configure sharing from your Linux host PC manually. Suppose you have an Internet connection through an ethernet cable interface, normally eth0. You can share this network connection with any other interface (USB, Bluetooth and/or WLAN) by executing the following commands:

$ iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
$ echo 1 > /proc/sys/net/ipv4/ip_forward

You can replace eth0 with any other interface (usb0, bnep0 or wlan0) that has a working Internet connection. To disable network sharing, you should execute the following commands:

$ iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
$ echo 0 > /proc/sys/net/ipv4/ip_forward

If you want to permanently share the network from your Linux host PC, you should edit the /etc/network/interfaces file. For example, you can add the following lines to it to share the network every time the USB interface (usb0) is up.

mapping hotplug
script grep
map usb0

iface usb0 inet dhcp
# commands to enable internet sharing
up iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
up echo 1 > /proc/sys/net/ipv4/ip_forward
# commands to disable internet sharing
down iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
down echo 0 > /proc/sys/net/ipv4/ip_forward

= Sharing network from Windows =

To share the Internet network from your Windows host PC, you should follow these steps:

* Open the '''Start - Control Panel - Network and Internet Connections - Network Connections''' dialog.
* Right click the interface from which you access the Internet.
* Select the '''Properties''' option.
* Select the '''Advanced''' tab.
* Under '''Internet Connection Sharing''', select the '''Allow other network users to connect through this computer's Internet connection''' check-box, figure [[#fig:pc_connectivity_mpc_win_internet_sharing|4.2]].
* Click on the '''OK''' button.

{| summary="Local Area Connection Properties dialog"
|+ align="BOTTOM" |'''Figure 4.2:''' Local Area Connection Properties dialog
|-
|
[[Image:mpc_win_internet_sharing.png|Image mpc_win_internet_sharing]]
|}

= Sharing network from Mac OS X =

To share the Internet network from your Mac OS X host PC, you should follow these steps:

* Go to '''System Preferences''' and click on the '''Sharing''' icon, figure [[#fig:pc_connectivity_mpc_mac_internet_sharing_preferences|4.3]].
* Select the '''Internet Sharing''' service.
* From '''Share your connection from''', select the interface that has an Internet connection. For example, ''AirPort'', figure [[#fig:pc_connectivity_mpc_mac_internet_sharing_properties|4.4]].
* From '''To computers using''', check the interfaces you want to share the Internet with. For example, '''Bluetooth PAN'''.
* Enable the '''Internet Sharing''' check-box.

{| summary="System Preferences dialog"
|+ align="BOTTOM" |'''Figure 4.3:''' System Preferences dialog
|-
|
[[Image:mpc_mac_internet_sharing_preferences.png|Image mpc_mac_internet_sharing_preferences]]
|}

{| summary="Network Sharing dialog"
|+ align="BOTTOM" |'''Figure 4.4:''' Network Sharing dialog
|-
|
[[Image:mpc_mac_internet_sharing_properties.png|Image mpc_mac_internet_sharing_properties]]
|}

Documentation/Maemo PC Connectivity Tutorial/Bibliography

2010-04-09T09:04:59Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

== Bibliography ==

; 1
: Cygwin Project. <tt>http://cygwin.org/</tt>.
; 2
: MacPorts Project. <tt>http://www.macports.org/</tt>.

----

Documentation/Maemo PC Connectivity Tutorial/Preface

2010-04-09T09:04:58Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Preface =

= Legal notice =

Copyright (c) 2008-2010 Nokia Corporation

Nokia and Maemo are trademarks or registered trademarks of Nokia Corporation. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.

= Disclaimer =

The information in this document is provided "as is," with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. This document is provided for informational purposes only. Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to implementation of information presented in this document. Nokia Corporation does not warrant or represent that such use will not infringe such rights.

Nokia Corporation retains the right to make changes to this material at any time, without notice.

= Licenses =

This document is licensed under the [http://www.gnu.org/copyleft/fdl.html GNU Free Documentation License, version 1.2].

Permission is granted to copy, distribute and/or modify documentation under the terms of the GNU Free Documentation License, version 1.2 or any later version published by the Free Software Foundation. Please refer to the copyright notice in each piece of documentation for Invariant Sections, Front-Cover Texts or Back-Cover Texts, if any, as defined in the License.

Documentation/Maemo For Symbian Developers Guide/Comparing Maemo and Symbian OS

2010-04-09T09:04:41Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Comparing Maemo and Symbian OS =

The picture below (figure [[#fig:maemo-for-symbian-dev-comparing-symbian-os-and-maemo-architectures|2.1]]) presents a direct comparison between the software components of both operating systems, although the the structure of the Maemo platform and the underlying GNU/Linux operating system differ significantly from Symbian OS. The picture shows the layered architecture of Symbian OS and tries to distribute the Maemo software components in layers according to their correspondent functionalities on the Symbian OS.

{| summary="Comparing Symbian OS and Maemo architectures"
|+ align="BOTTOM" |'''Figure 2.1:''' Comparing Symbian OS and Maemo architectures
|-
|
[[Image:MaemoSymbianArchitecture.png|Image MaemoSymbianArchitecture]]
|}

In some cases Symbian OS subsystems and APIs can be directly mapped to Maemo platform components, but usually the relations are not 1:1. Therefore, this chapter provides just a generalized comparison of the platforms.

The table below (table 2.1) compares the main software components of the Symbian platform with those of the Maemo platform. This table can be used as a quick reference to find the proper software component that should be used in the Maemo platform given the desired component of the Symbian platform. Also, the table shows some components that are specific to Maemo platform, explaining their use.

{| border="1" cellpadding="3"
|+ '''Table 2.1:''' Comparison between Maemo and Symbian platforms
|-
| width="100" align="LEFT" valign="TOP" |
'''Symbian Component'''
! width="100" align="LEFT" valign="TOP" | '''Maemo Component'''
! width="250" align="LEFT" valign="TOP" | '''Description'''
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" |
| width="250" align="LEFT" valign="TOP" |
|-
| colspan="3" align="LEFT" | '''''Base Services'''''
|-
! width="100" align="LEFT" valign="TOP" | '''DBMS'''
| width="100" align="LEFT" valign="TOP" | '''SQLite'''
| width="250" align="LEFT" valign="TOP" |
The Maemo platform provides an SQL database, SQLite 3, which can be used to store user application data. The SQLite database is accessed through a library interface whose documentation can be found [http://www.sqlite.org/capi3.html here].
|-
! width="100" align="LEFT" valign="TOP" | '''File server'''
| width="100" align="LEFT" valign="TOP" | '''GnomeVFS'''
| width="250" align="LEFT" valign="TOP" |
The system uses the GnomeVFS, which is an extendable file system abstraction library that applies transparent access to different file systems types. More information can be found [http://library.gnome.org/devel/gnome-vfs-2.0/unstable/ here].
|-
! width="100" align="LEFT" valign="TOP" | '''ECOM framework'''
| width="100" align="LEFT" valign="TOP" | '''Core libs'''
| width="250" align="LEFT" valign="TOP" |
There is no direct equivalent component for the ECOM framework on the Maemo platform. The developer may use the dynamic load of modules (GModule) provided by Glib library. It is implemented in C and there is no support for automatic module load. Code must be written by the developer in order to do this. GModule API can be found [http://library.gnome.org/devel/glib/stable/glib-Dynamic-Loading-of-Modules.html here].
|-
! width="100" align="LEFT" valign="TOP" | '''Central repository'''
| width="100" align="LEFT" valign="TOP" | '''Libosso, GConf '''
| width="250" align="LEFT" valign="TOP" |
There is no Central Repository for system information in Maemo. To recover system information such as device state and mode, the developer may use libosso. To store application specific settings, the developer can use GConf component. See more [http://projects.gnome.org/gconf/ here].
|-
! width="100" align="LEFT" valign="TOP" | '''User library'''
| width="100" align="LEFT" valign="TOP" | '''GNU C / LibStd C++'''
| width="250" align="LEFT" valign="TOP" |
The user library defines the core idioms for Symbian OS programming. In Maemo development, this is based on standard C/C++ so the matching for the core idioms could be [http://gcc.gnu.org/onlinedocs/libstdc++/ GNU C / LibStd C++].
|-
! width="100" align="LEFT" valign="TOP" | '''Cryptographic library'''
| width="100" align="LEFT" valign="TOP" | '''OpenSSL'''
| width="250" align="LEFT" valign="TOP" |
This library includes some non-RSA algorithms, hash functions, and so on, that are easily found in [http://www.openssl.org/ OpenSSL] library.
|-
! width="100" align="LEFT" valign="TOP" | '''Store'''
| width="100" align="LEFT" valign="TOP" |

| width="250" align="LEFT" valign="TOP" | Provides an abstraction for internalizing and externalizing objects to different storage media. There is no equivalent component in Maemo. Glib binding for D-Bus has some primitive functions to do object marshal. However there are plenty of open source projects that provide serialization tools for C++. The developer may use the preferred one.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Video4Linux'''
| width="250" align="LEFT" valign="TOP" | A Linux kernel integrated video capture API. It supports several types of cameras.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''dpkg'''
| width="250" align="LEFT" valign="TOP" | dpkg is the software at the base of the debian package management system that is used in Maemo. dpkg is used to install, remove and provide information about .deb packages files that are the software installation unit for Maemo in comparison to the .sisx files of Symbian OS.
|-
| colspan="3" align="LEFT" | '''''OS Services'''''
|-
! width="100" align="LEFT" valign="TOP" | '''Certificate management'''
| width="100" align="LEFT" valign="TOP" | '''OpenSSL'''
| width="250" align="LEFT" valign="TOP" | Certificate management is done by OpenSSL in the Maemo platform. This system library offers similar mechanisms to store and manage certificates, keys, and so on.
|-
! width="100" align="LEFT" valign="TOP" | '''MMF, Camera'''
| width="100" align="LEFT" valign="TOP" | '''MAFW, gStreamer'''
| width="250" align="LEFT" valign="TOP" | The MAFW was added to the Frematle Maemo version and provides a highly modular infrastructure for consuming and extending Maemo's multimedia functionality. MAFW is an abstraction layer that is largely decoupled from its underlying components. It will be possible to snap in a number of media backends, such as GStreamer and MPlayer. The gStreamer, that was used to handle multimedia in previous versions, has a similar design choice as MMF. It has a minimum core, and functionalities are added through plug-ins. It also makes use of pipeline through sinks and sources for each element to build the wanted operation.
|-
! width="100" align="LEFT" valign="TOP" | '''ICL'''
| width="100" align="LEFT" valign="TOP" | '''Cairo, GDK'''
| width="250" align="LEFT" valign="TOP" | These libraries handle a wide number of image types.
|-
! width="100" align="LEFT" valign="TOP" | '''OpenGL ES'''
| width="100" align="LEFT" valign="TOP" | '''OpenGL ES'''
| width="250" align="LEFT" valign="TOP" | Until Maemo 4.1 (Diablo) Open GL ES was not supported. In Maemo 5 (Fremantle) OpenGL ES 2.0.
|-
! width="100" align="LEFT" valign="TOP" | '''Window Server'''
| width="100" align="LEFT" valign="TOP" | '''X'''
| width="250" align="LEFT" valign="TOP" | X Window System, that provides windowing on bitmap displays and event handling from inputs. Low level, usually not used directly by the developer.
|-
! width="100" align="LEFT" valign="TOP" | '''Font and Bitmap Server'''
| width="100" align="LEFT" valign="TOP" | '''Pango'''
| width="250" align="LEFT" valign="TOP" | Library for laying out and rendering of text, with an emphasis on internationalization. It forms the core of text and font handling for GTK+.
|-
! width="100" align="LEFT" valign="TOP" | '''Device Backup'''
| width="100" align="LEFT" valign="TOP" | '''Backup'''
| width="250" align="LEFT" valign="TOP" | Maemo has an application that can backup user data and application configuration on a memory card. At time of writing there is no support for remote device backup on Maemo.
|-
! width="100" align="LEFT" valign="TOP" | '''Remote file management '''
| width="100" align="LEFT" valign="TOP" |

| width="250" align="LEFT" valign="TOP" | There is no API for remote file management.
|-
! width="100" align="LEFT" valign="TOP" | '''Remote SW'''
| width="100" align="LEFT" valign="TOP" |

| width="250" align="LEFT" valign="TOP" | There is no equivalent component for remote software installation in the Maemo platform.
|-
! width="100" align="LEFT" valign="TOP" | '''Telephony server, SMS utilities, WAP stack'''
| width="100" align="LEFT" valign="TOP" |

| width="250" align="LEFT" valign="TOP" | There is no equivalent component in the Maemo platform.
|-
! width="100" align="LEFT" valign="TOP" | '''TCP/IP + security'''
| width="100" align="LEFT" valign="TOP" | '''Core libs'''
| width="250" align="LEFT" valign="TOP" | Low-level operating system APIs (file and network handling, standard C libraries). SSL and TLS are supported through OpenSSL.
|-
! width="100" align="LEFT" valign="TOP" | '''Bluetooth'''
| width="100" align="LEFT" valign="TOP" | '''BlueZ'''
| width="250" align="LEFT" valign="TOP" |
Official Bluetooth stack for GNU/Linux. More information can be found [http://www.bluez.org/ here].
|-
! width="100" align="LEFT" valign="TOP" | '''OBEX'''
| width="100" align="LEFT" valign="TOP" | '''Obex'''
| width="250" align="LEFT" valign="TOP" |
The Maemo platform makes use of [http://sourceforge.net/projects/openobex Openobex] implementation.
|-
! width="100" align="LEFT" valign="TOP" | '''CommDB'''
| width="100" align="LEFT" valign="TOP" |

| width="250" align="LEFT" valign="TOP" | There is no specific shared data base for communication settings in Maemo. Even CommDB use in Symbian OS is being replaced by Central Repository. You can use GConf to store data or even SQLite.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''GUPnP'''
| width="250" align="LEFT" valign="TOP" |
GUPnP is an object-oriented open source framework for creating [http://www.upnp.org/ UPnP] devices and control points, written in C using [http://developer.gnome.org/doc/API/2.0/gobject/index.html GObject] and [http://live.gnome.org/LibSoup libsoup].
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''D-Bus'''
| width="250" align="LEFT" valign="TOP" | The D-BUS message bus system is used for applications and libraries to deliver messages to each another.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''System SW'''
| width="250" align="LEFT" valign="TOP" | The System Software subsystem provides system-wide services to applications and users. The services include device state management (dsm), mode control (mce), battery management (bme) and a few graphical user interface elements to manage the behaviour of the services.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Clipboard'''
| width="250" align="LEFT" valign="TOP" | In Maemo, there are a number of clipboard enhancements to the X clipboard and Gtk+, in order to enable: supporting retaining the clipboard data, when applications owning the clipboard exit; copying and pasting rich text data between Gtk+ text views in different applications; providing a generally more pleasant user experience; making it easy for application developers to gray out '''Paste''' menu items when the clipboard data format is not supported by the application.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Farsight2'''
| width="250" align="LEFT" valign="TOP" |
[http://farsight.freedesktop.org/wiki/FrontPage Farsight2] is an Audio/Video Communications Framework. The main target clients for Farsight are Instant Messaging applications. It uses gStreamer for all its media streaming needs.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''FM transmitter'''
| width="250" align="LEFT" valign="TOP" |
[[Documentation/Maemo 5 Developer Guide/Using Multimedia Components/FM Transmitter API Usage|Maemo API to access FM transmitter]] radio.
|-
| colspan="3" align="LEFT" | '''''Application Services'''''
|-
! width="100" align="LEFT" valign="TOP" | '''PIM'''
| width="100" align="LEFT" valign="TOP" | '''EDS'''
| width="250" align="LEFT" valign="TOP" |
The [http://www.go-evolution.org/EDS_Architecture Evolution Data Server] provides a single database for common, desktop-wide information, such as a user's address book or calendar events.
|-
! width="100" align="LEFT" valign="TOP" | '''Messaging system'''
| width="100" align="LEFT" valign="TOP" | '''Telepathy'''
| width="250" align="LEFT" valign="TOP" | The Telepathy project aims to provide a unified framework for all forms of real time conversations, including instant messaging, IRC, voice calls, and video calls.
|-
! width="100" align="LEFT" valign="TOP" | '''Data synchronization'''
| width="100" align="LEFT" valign="TOP" | '''SyncML'''
| width="250" align="LEFT" valign="TOP" |
Maemo supports SyncML. More information [http://syncevolution.org/ here].
|-
! width="100" align="LEFT" valign="TOP" | '''Internet, web and multimedia protocol support (RTP, SIP, HTTP)'''
| width="100" align="LEFT" valign="TOP" | '''Telepathy, gStreamer, curl HTTP'''
| width="250" align="LEFT" valign="TOP" |
For SIP and a great number of different session protocols, Maemo uses [http://telepathy.freedesktop.org/wiki/ Telepathy]. For RTP you can use [http://gstreamer.freedesktop.org/ GStreamer] and for HTTP you can use [http://curl.haxx.se/ curl HTTP] that supports FTP, TELNET, HTTP, HTTPS, and so on.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''PulseAudio'''
| width="250" align="LEFT" valign="TOP" |
[http://pulseaudio.org/ PulseAudio] is a sound server for POSIX and Win32 systems. A sound server is basically a proxy for your sound applications. It allows you to do advanced operations on your sound data as it passes between your application and your hardware. Things like transferring the audio to a different machine, changing the sample format or channel count and mixing several sounds into one are easily achieved using a sound server. Maemo 5 uses PulseAudio.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''GSF'''
| width="250" align="LEFT" valign="TOP" |
The GNOME Structured File Library ([http://library.gnome.org/devel/gsf/unstable/index.html GSF]) is an I/O abstraction for reading/writing compound files.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Installer'''
| width="250" align="LEFT" valign="TOP" | Application installer includes automatic dependency management. Uses a standard debian package format.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Alarm Framework'''
| width="250" align="LEFT" valign="TOP" | The Maemo alarm framework provides an easy way to manage timed events in the device. It is powerful, and not restricted only to wake-up alarms. The framework provides also many other features.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Launcher'''
| width="250" align="LEFT" valign="TOP" | Maemo Launcher launches most applications on the Maemo platform. It is there to speed up the application start-up by sharing some of the initialization data of an application start-up. Maemo Launcher is composed of two parts: (I) the Maemo-invoker, which is executed by D-BUS daemon or scripts to start the given (application) service, and (II) Maemo-launcher, a server that has initialized most of the data used by the applications.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Vibra service'''
| width="250" align="LEFT" valign="TOP" | A new service added in Fremantle. The access can be made through D-BUS.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Device orientation'''
| width="250" align="LEFT" valign="TOP" | An API that enable developers to respond to changes in orientation and discover current orientation.
|-
| colspan="3" align="LEFT" | '''''UI Framework'''''
|-
! width="100" align="LEFT" valign="TOP" | '''Uikon, Avkon, CONE'''
| width="100" align="LEFT" valign="TOP" | '''GTK+'''
| width="250" align="LEFT" valign="TOP" | A widget toolkit for the X Window System, for creating GUIs. The used GTK+ has been modified for the Maemo platform, but it is binary compatible with the original.
|-
! width="100" align="LEFT" valign="TOP" | '''FEP'''
| width="100" align="LEFT" valign="TOP" | '''Input methods'''
| width="250" align="LEFT" valign="TOP" | The Maemo platform is intended to be used on embedded devices. It is a quite straightforward request that one might want to have different input methods from the ones available by default, or just simply want a different layout for the virtual keyboard. For this reason, Maemo 4.1 introduced a way to enable writing custom plug-ins for Hildon Input Method.
|-
! width="100" align="LEFT" valign="TOP" | '''Animation'''
| width="100" align="LEFT" valign="TOP" | '''Clutter'''
| width="250" align="LEFT" valign="TOP" | Clutter provides a very clean high-level API for developing sophisticated animations on top of OpenGL ES.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Matchbox'''
| width="250" align="LEFT" valign="TOP" |
[http://matchbox-project.org/ Matchbox] is an Open Source base environment for the X Window System running on non-desktop embedded platforms. Matchbox consists of a number of interchangeable and optional applications that can be tailored to a specific non desktop platform to enhance usability in a ''constrained'' environment.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Tracker'''
| width="250" align="LEFT" valign="TOP" |
Provides tracker (mod, s3m, and so on) music support for built-in music player. More information about the project can be found [https://garage.maemo.org/projects/mgstmodplug/ here].
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Hildon Control Panel'''
| width="250" align="LEFT" valign="TOP" | Hildon Control Panel is a general interface for application configuration and is extended by control panel plug-ins.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Hildon Home Applets'''
| width="250" align="LEFT" valign="TOP" | Hildon Home is the root desktop, which can be customized by Hildon home applets.
|-
| width="100" align="LEFT" valign="TOP" |
| width="100" align="LEFT" valign="TOP" | '''Hildon Status bar'''
| width="250" align="LEFT" valign="TOP" | Hildon Status bar provides area for information and quick-access items used mainly to communicate device status changes.
|}

----

Documentation/Maemo For Symbian Developers Guide

2010-04-09T09:04:41Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

{| width="100%"
|
Nokia Corporation = MAEMO FOR SYMBIAN DEVELOPERS GUIDE =<div class="author_info">'''maemo.org''''''18 February 2010'''</div>
|}

----

<div class="margins">

* [[{{PAGENAME}}/Preface|Preface]]
* [[{{PAGENAME}}/Glossary|Glossary]]
* [[{{PAGENAME}}/Introduction|Introduction]]
* [[{{PAGENAME}}/Comparing Maemo and Symbian OS|Comparing Maemo and Symbian OS]]
* [[{{PAGENAME}}/Maemo and Symbian OS Concepts|Maemo and Symbian OS Concepts]]
* [[{{PAGENAME}}/Bibliography|Bibliography]]

</div>

----

Documentation/Maemo For Symbian Developers Guide/Maemo and Symbian OS Concepts

2010-04-09T09:04:40Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Maemo and Symbian OS Concepts =

The Symbian OS is famous for its design, concepts, and coding conventions. The Maemo platform gives the developer more freedom, but it also requires the developer to take more responsibility. The Maemo platform does not enforce any specific design patterns, so the developer is responsible for preventing memory leaks, buffer overflows, and other security problems.

Programming in Maemo is closer to desktop programming than Symbian programming is. This is because it is based on Linux, which was created for desktop environments, whereas Symbian OS was specifically developed for resource constrained systems. For this reason, the Maemo developer has more freedom than the Symbian developer.

The following topics show the main programming differences for both environments.

= Programming languages and libraries =

Symbian developers must obey a lot of coding conventions to write code correctly. In Maemo this is no longer necessary because Maemo uses standard C and C++. Most software developed for the Maemo platform is written in C. This software widely uses Glib utility library that provides the object model adopted for Maemo (GObject). However, C++ applications can also be written since there are several C++ bindings available for different libraries in the Maemo platform. Despite these bindings, C library calls should be made in code written for the Maemo platform sooner or later due to the fact that most part of the platform uses standard C and Glib. Due to Open C/C++, the Symbian developer should already be aware of the use of these libraries as well as STL, boost, and others C/C++ libraries.

= Symbian OS essential concepts =

Some differences between Symbian C++ and C++ used in Maemo are listed below. These differences are more about the conventions, concepts, and software design. Some replacements for missing Symbian/C++ specific concepts are also introduced.

== Naming guidelines ==

Symbian OS naming conventions like class names prefix (C, M, R, or T), function leave indication (L suffix) are left behind when programming for Maemo platform. In Maemo, the developer is given more freedom and there are no mandatory prefixes in class names. Although there are no strict rules to be followed, Maemo has some programming guidelines that should be considered. Some examples are given below:

Descriptive, lower-case names should be used for variables and functions. Underscores (_) can be used to indicate word boundaries. Non-static and unnecessary global names should be avoided. If it is absolutely necessary to employ a global variable, type or function, one should use a prefix specific to the library or module where the name is, e.g. gtk_widget_.

Static memory (variables) should be preferred to dynamic memory, when the needed memory size is not large and/or is used regularly in the program. Static memory does not leak, a pointer to static memory is less likely to cause a segmentation fault, and using static memory keeps the memory usage more constant.

Local variables should always be favoured over global variables, i.e. the visibility of a variable should be kept at a minimum. Global variables should not be used to pass values between functions: this can be performed with arguments. Note: Global variables require extra care when programming with threads. Thus, these should be avoided.

== Runtime type information ==

Symbian OS supports runtime type information (RTTI) only from Symbian OS v9 onwards. In Maemo, run time type information was available since the beginning. In both cases, the [http://www.cplusplus.com/doc/tutorial/typecasting/ dynamic_cast] operator is used to retrieve RTTI.

== Exceptions ==

Symbian/C++ developers are familiar with concepts like ''leaving'' and ''trap harness'' because standard [http://www.cplusplus.com/doc/tutorial/exceptions/ C++ exceptions] did not exist when Symbian OS was originally developed. Only from Symbian OS v9 onwards C++ were exception mechanisms supported, although they still should not be mixed with Symbian/C++ code. In Maemo the standard C++ exceptions (try, catch, throw) are available.

== Cleanup stack ==

A Symbian/C++ specific concept that is not available in the Maemo platform. Similar functionality can be achieved by using [http://en.wikipedia.org/wiki/Auto_ptr auto_ptr] class which is also available for Symbian v9 onwards. auto_ptr is a [http://en.wikipedia.org/wiki/Smart_pointer smart pointer] implementation in [http://en.wikipedia.org/wiki/Standard_Template_Library C++ Standard Template Library], and it is a good way to prevent memory leaks in case of exceptions ([http://maemo4mobile.garage.maemo.org/snippet_autoptr.html view example]).

For more information on using the auto_ptr, see the article [http://www.gotw.ca/publications/using_auto_ptr_effectively.htm Using auto_ptr Effectively].

= Class construction =

The Symbian OS documentation states that if a class has to allocate memory, it should be derived from CBase. In Maemo, there is no such base class. This design causes some differences.

== Class inheritance ==

In Symbian/C++ multiple inheritances are only allowed when combining multiple M-classes and one CBase derived class. This is the same approach adopted by Java that allows multiple interfaces implementations and only one class derivation per class. The reason is that multiple inheritances can become too complicated. Maemo does not impose any limits to the inheritance mechanism, so the developer has more freedom as well as more responsibility.

== Two-phased construction ==

Since the full C++ exception mechanism is used in Maemo (which includes stack unwinding), the two-phased construction of objects is not needed any more. The developer should use smart pointers to store pointers which may leak in case of exceptions. See the brief example from listing below:

<code>class MyInnerClass
{
public:
MyInnerClass(){}
}<nowiki>;

/* ----------------------------------------------- */
class MyClass
</nowiki>{
public:
MyClass();

private:
auto_ptr<MyInnerClass> m_inner;
}<nowiki>;

MyClass::MyClass() : m_inner (new MyInnerClass())
</nowiki>{
}

/* ----------------------------------------------- */
void functionFoo()
{
auto_ptr<MyClass> myAutoObject(new MyClass());
/* IF THROW HERE ....*/
}</code>

In the example above, exceptions may be thrown after the instantiation of myAutoObject or in the construction of MyInnerClass. In both cases the objects do not leak memory due to the use of auto_ptr class that holds the pointer of the objects and call the destructor in case of leave and end of scope. A good explanation can be found [http://www.parashift.com/c++-faq-lite/exceptions.html#faq-17.4 here].

= Descriptors =

Descriptors class was specifically designed for Symbian OS and does not exist as such in the Maemo platform.

= Strings =

When working with strings, instead of descriptors you can use the C-style NULL-terminated character arrays and methods.

'''Null-terminated character arrays using standard C'''

[http://en.wikipedia.org/wiki/String.h The C-style NULL-terminated character arrays and methods] can be used to store strings only. They are not as safe because they can cause buffer overflow. They can only be used with character set based on ASCII. One advantage is that it is guaranteed to work on any platform which supports C.

'''NULL-terminated character arrays using Glib'''

GLib is extensively used in the Maemo platform, so it is good practice to use the [http://library.gnome.org/devel/glib/stable/glib-String-Utility-Functions.html GLib-provided types and methods if using character arrays], although nothing prevents the developer from using other types.

See the [http://maemo4mobile.garage.maemo.org/snippet_gchar.html example].

=== GString ===

[http://library.gnome.org/devel/glib/stable/glib-Strings.html GString] from the Glib. Similar to a standard C string, except that it grows automatically when text is appended or inserted. Also, it stores the length of the string, so it can be used for binary data which contains bytes with NULL values.

See the [http://maemo4mobile.garage.maemo.org/snippet_gstring.html example].

== String class ==

[http://en.wikipedia.org/wiki/String_(C++) String class] from the [http://en.wikipedia.org/wiki/Standard_Template_Library C++ Standard Template Library]. The string class resizes automatically when necessary.

See the [http://maemo4mobile.garage.maemo.org/snippet_stlstring.html example].

== Binary data ==

If you are working with binary data, you can use:

* Low-level, C-language memory allocation and [http://en.wikipedia.org/wiki/String.h handling].
* GArray from GLib - arrays of arbitrary elements which grow automatically as elements are added.
* GString that works also with binary data, as it stores the data length.
* [http://en.wikipedia.org/wiki/Standard_Template_Library#Containers C++ containers] (for example, vectors and lists).

= Active objects and threads =

Symbian OS discourages the usage of threads because context switching is considered an expensive operation which degrades battery life. Basically, this is true in the Maemo platform too, but avoiding threads at all cost is not required.

Using the main event loop of GLib it is possible to run several asynchronous operations in a single thread, without blocking. This is fairly similar to using Active Objects. Examples of sources of events are file descriptors, sockets, even timeouts, and so on.

Below you see a timeout example function with event loop (based on [http://w00d5t0ck.info/gnome_tutorial/gnome_tutorial.html#AEN53 Gnome developers' tutorial]).

<code><nowiki>
#include

#define COUNT_UNTIL 2
#define TIMEOUT 2

static int counter;

GMainLoop *main_loop;

gboolean

timeout_func(gpointer data)
{
counter++;
g_printf("Running for the %d. time.\n", counter);
if (counter == COUNT_UNTIL)
{
g_main_loop_quit(main_loop);
return FALSE;
}
return TRUE;
}

int
main(int argc, char **argv)
{
counter = 0;
main_loop = g_main_loop_new(NULL, FALSE);
g_timeout_add_seconds(TIMEOUT, timeout_func, NULL);
g_main_loop_run(main_loop);
return 0;
}
</nowiki></code>

In case of dealing with threads you can use:

* [http://en.wikipedia.org/wiki/POSIX_Threads POSIX threads] (the traditional Unix-style operating system type)
* GThread from GLib

= Static data in DLLs =

In Symbian OS version before v9 static data in DLLs was not supported. From v9 onwards static data is supported but it consumes big amounts of RAM memory. The Maemo platform does not have this limitation. You can use, for example, global variables in your shared libraries. Note, however, that the static data is not shared between the processes.

= Platform security =

Platform security does not exist in the Maemo platform. When installing software with the Application Manager, it only warns if the software is NOT being downloaded from the official Maemo repositories. The Maemo does not have a specific scheme to enforce platform security as Symbian has. One benefit is that installing software in Maemo is more developer-friendly than in Symbian.

= Client-server model =

Whereas Symbian OS extensively uses a client/server approach with asynchronous method calls, the Maemo platform uses direct, synchronous API calls. Usually this means that called functions block until they finish, with some exceptions.

Using sockets is a good example of the differences between the Symbian OS and Maemo platforms, regarding the client-server model vs. direct API calls. See [http://maemo4mobile.garage.maemo.org/snippet_clientserver_sync.html networking example].

Documentation/Maemo For Symbian Developers Guide/Glossary

2010-04-09T09:04:40Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

Documentation/Maemo For Symbian Developers Guide/Introduction

2010-04-09T09:04:39Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Introduction =

This document aims to compare Symbian and Maemo OS at architectural level, providing a didactic matching between the different components of each operating system, so that Symbian OS developers can easily learn what software component they should use in Maemo platform for each functionality.

Maemo is an open source development platform for Linux-based handheld devices. It is built from widely-used open source components with additional tweaks to integrate well in handheld devices.

{| summary="Maemo device - N900"
|+ align="BOTTOM" |'''Figure 1.1:''' Maemo device - N900
|-
|
[[Image:Nokia_N900_39.png|Image Nokia_N900_39]]
|}

An Maemo device is a handheld device which provides desktop PC-level support for Internet services (such as Web pages and e-mail). Nokia has released several Maemo devices running the Maemo platform: the Nokia 770, the Nokia N800, Nokia N810, Nokia N810 WiMAX Edition and N900, see figure [[#fig:maemo-for-symbian-dev-introduction-n900|1.1]]. The devices have a high-resolution, 800 x 480 pixel touch-sensitive display.

Maemo uses Hildon Application Framework, based on the open source GTK+ toolkit, as the user interface manager. Although the Hildon/GTK+ libraries are coded in C, bindings for other languages, including C++ and Python, are also available.

The native programming language for Symbian OS devices is C++. So, any S60 developer can take advantage of the Hildon/GTK+ C++ bindings and easily start developing GUI applications for Maemo devices. This document demonstrates how a Symbian C++ developer can get started with developing applications for Maemo platform.

Before you start to write your own applications for Maemo, learn more about the Maemo platform and the Hildon Application Framework. For more information, see documents ''GNOME Programming Guidelines'' <ref name=r4>Federico Mena Quintero, Miguel de Icaza, and Morten Welinder. GNOME Programming Guidelines. http://developer.gnome.org/doc/guides/programming-guidelines/book1.html</ref>, ''GTK+ Reference Manual'' <ref name=r1>GTK+ Reference Manual. http://library.gnome.org/devel/gtk/unstable/index.html</ref>, ''Hildon'' <ref name=r2>Hildon Project. http://live.gnome.org/Hildon/</ref>, and ''Maemo Fremantle Developer Guide'' <ref name=r3>Maemo Fremantle Developer Guide. http://library.maemodocs.nokia.com</ref>.

----
== References ==
<references />

Documentation/Maemo For Symbian Developers Guide/Bibliography

2010-04-09T09:04:39Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

== Bibliography ==

; 1
: GTK+ Reference Manual. <tt>http://library.gnome.org/devel/gtk/unstable/index.html</tt>.
; 2
: Hildon Project. <tt>http://live.gnome.org/Hildon/</tt>.
; 3
: Maemo Fremantle Developer Guide. <tt>http://library.maemodocs.nokia.com</tt>.
; 4
: Federico Mena Quintero, Miguel de Icaza, and Morten Welinder. GNOME Programming Guidelines. <tt>http://developer.gnome.org/doc/guides/programming-guidelines/book1.html</tt>.

----

Documentation/Maemo For Symbian Developers Guide/Preface

2010-04-09T09:04:38Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

Documentation/Maemo Flasher-3.5 Tutorial/Maemo Flasher-3.5 tool

2010-04-09T09:04:37Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Maemo Flasher-3.5 tool =

= Release details =

Maemo Flasher-3.5 tool release information:

* Version: 2.5.2 - Final
* Date: October 23, 2009
* Hardware supported: Nokia N800, N810 and N810 WiMAX Edition with Diablo 4.1.x and N900 with Fremantle 5.x

= Delivery packages =

Maemo Flasher-3.5 tool delivery archive content:

; '''flasher-3.5'''
: flasher binary file (flasher-3.5.exe for Windows)
; '''libusb'''
: USB library (only for Windows and Mac OS X installations)
; '''COPYING_LGPL.txt'''
: license text for libusb (only for Windows and Mac OS X installations)
; '''License_Agreement.txt'''
: license and disclaimer text for flasher binary
; '''Help.txt'''
: short command line help
; '''Readme_Maemo_Flasher-3.5.txt'''
: Flasher-3.5 readme file

= Downloads and documentation =

Maemo Flasher-3.5 download: [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php Maemo Development Environment Downloads] page

Maemo Flasher-3.5 documentation: This document and documentation delivered as part of installation packages (readme and help files)

Sources for libusb library (LGPL v2) installed as part of Maemo Flasher-3.5 for Windows and Mac OS X:

* Libusb (Mac): [http://pc-connectivity.garage.maemo.org/upstream/libusb-0.1.12.tar.gz libusb-0.1.12.tar.gz]
* Libusb-win32 (Win): [http://pc-connectivity.garage.maemo.org/upstream/libusb-win32-src-0.1.12.1.tar.gz libusb-win32-src-0.1.12.1.tar.gz]

Original libusb sources are available from SourceForge.net:

* Libusb (Mac): [http://ufpr.dl.sourceforge.net/sourceforge/libusb libusb]
* Libusb-win32 (Win): [http://ufpr.dl.sourceforge.net/sourceforge/libusb-win32 libusb-win32]

Documentation/Maemo Flasher-3.5 Tutorial/Glossary

2010-04-09T09:04:36Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Glossary =

; '''eMMC'''
: Describes an architecture consisting of an embedded storage solution with MMC interface, flash memory and controller, all in a small ball grid array package.
; '''FIASCO'''
: An open source Fractal Image And Sequence Codec, is a compression method used to compress Maemo device images.
; '''ID'''
: Identifier.
; '''Maemo'''
: Software platform for mobile devices developed by Nokia, based on GNU/Linux and GNOME/GTK+ technologies. It includes proprietary components to make it work on the Nokia Maemo compatible device.
; '''maemo.org'''
: Developer community web site maintained by Nokia, main point of reference for open source and third-party developers in general.
; '''MMC'''
: MultiMediaCard, is a flash memory memory card standard.
; '''NAND'''
: "Not AND" is a type of Flash Memory technology.
; '''OS'''
: Operating System or sometimes Open Source.
; '''PPC'''
: PowerPC or Performance Optimization With Enhanced RISC - Performance Computing, is a RISC architecture created by the 1991 Apple - IBM - Motorola alliance.
; '''USB'''
: Universal Serial Bus is a specification to establish communication between devices and a host controller (usually personal computers).
; '''VM'''
: Virtual Machine.
; '''WiMAX'''
: Worldwide Interoperability for Microwave Access, is a telecommunications technology that provides wireless transmission of data using a variety of transmission modes.

= Maemo Releases =

; '''Mistral'''
: Maemo 2.0 release for Nokia 770 device. Corresponds to the Nokia Internet Tablet SE 2006 version 2.01.2006.26-8.
; '''Scirocco'''
: Maemo 2.1 release for Nokia 770 device. Includs mainly bugfixes and some other enhancements. Corresponds to Nokia Internet Tablet SE 2006 version 2.2006.39-14.
; '''Gregale'''
: Maemo 2.2 release for Nokia 770 device (bugfixes and enhancements).
; '''Bora'''
: Maemo 3.x releases for Nokia N800 device. Corresponds to Internet Tablet OS releases "1.2006.47-20", "2.2006.51-6" (Maemo 3.0), "3.2007.10-7" (Maemo 3.1) and "4.2007.26-8"+"4.2007.38-2" (Maemo 3.2).
; '''Chinook'''
: Maemo 4.0.x releases for Nokia N800 and N810 devices. Corresponds to Internet Tablet OS releases "1.2007.44-4" (Maemo 4.0) and "2.2007.51-3" (Maemo 4.0.1)
; '''Diablo'''
: Maemo 4.1.x releases for Nokia N800, N810 and N810 WiMAX devices. Corresponds to Internet Tablet OS releases "4.2008.23-14" (Maemo 4.1), "4.2008.36-5" (Maemo 4.1.1) and "5.2008.43-7" (Maemo 4.1.2)
; '''Fremantle'''
: Maemo 5.x releases for N900 device. Corresponds to Maemo 5 OS release "1.2009.42-11" + eMMC content "1.2009.41-1" (Maemo 5) and OS release "2.2009.51-1" + eMMC content "1.2009.41-1" (Maemo 5 Update)
; '''Harmattan'''
: Maemo 6.x releases, corresponds to Maemo 6 OS release "x.2010.xx-x"

Documentation/Maemo Flasher-3.5 Tutorial

2010-04-09T09:04:36Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

{| width="100%"
|
Nokia Corporation = MAEMO FLASHER-3.5 TUTORIAL =<div class="author_info">'''maemo.org''''''18 February 2010'''</div>
|}

----

<div class="margins">

* [[{{PAGENAME}}/Preface|Preface]]
* [[{{PAGENAME}}/Glossary|Glossary]]
* [[{{PAGENAME}}/Introduction|Introduction]]
* [[{{PAGENAME}}/Maemo Flasher-3.5 tool|Maemo Flasher-3.5 tool]]
* [[{{PAGENAME}}/Installation|Installation]]
* [[{{PAGENAME}}/Usage|Usage]]
* [[{{PAGENAME}}/Bibliography|Bibliography]]

</div>

----

Documentation/Maemo Flasher-3.5 Tutorial/Introduction

2010-04-09T09:04:35Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Introduction =

The Maemo Flasher-3.5 tool is host PC utility used to flash data to the Maemo device internal NAND memory. Maemo devices keep their bootloader, kernel, and rootfs (all of which make up the operating system) firmware components stored to the NAND memory. Maemo Flasher-3.5 can be used to upgrade the firmware, flash specific firmware components, or change a number of hardware flags.

Maemo Flasher-3.5 tool support following Maemo devices and platform releases:

* Nokia N800, N810 and N810 WiMAX Edition with Diablo 4.1.x.
* Nokia N900 with Fremantle 5.x, see figure [[#fig:flasher-3.5-tutorial-introduction-n900|1.1]].

{| summary="Maemo device - N900"
|+ align="BOTTOM" |'''Figure 1.1:''' Maemo device - N900
|-
|
[[Image:Nokia_N900_39.png|Image Nokia_N900_39]]
|}

----

Documentation/Maemo Flasher-3.5 Tutorial/Installation

2010-04-09T09:04:35Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Installation =

The Maemo Flasher-3.5 tool must be installed from the installation package provided for Debian based Linuxes, Windows and Mac OS X. For Linux distributions other than Debian-based ones, a compressed tar file is provided.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Installation of Maemo Flasher-3.5 requires administration rights in all supported operating systems.
|}

Maemo Flasher-3.5 tool supports following 32-bit host PC operating systems:

* Debian based Linuxes (with Debian installation package).
* Other Linuxes (with tar installation package).
* Windows XP with SP3, Vista with SP2 and Windows 7 (with Windows installation package).
* Mac OS X 10.5 Leopard and 10.6 Snow Leopard (with Mac OS X installation package).

Linux and Windows versions of Maemo Flasher-3.5 tool support x86/32-bit host PC architectures.

Mac OS X versions of Maemo Flasher-3.5 tool support x86/32-bit and PPC/32-bit architectures.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Maemo Flasher-3.5 tools do not support any 64-bit operating systems.
|}

Workaround for 64-bit operating systems that support either VMware, VirtualBox or QEMU virtualisation technologies is to install Maemo SDK Virtual Image from the [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php Maemo Development Environment Downloads] page (see document ''Maemo SDK Virtual Image Tutorial'' <ref name=r1>Maemo SDK Virtual Image Tutorial. http://library.maemodocs.nokia.com</ref> for more information) and install and run Maemo Flasher-3.5 from the image. If host PC hardware, operating system and chosen virtualisation technology have good enough support for USB port, flashing Maemo device from Maemo SDK Virtual Image should work.

Maemo Flasher-3.5 tools for different operating systems can be downloaded from the [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php Maemo Development Environment Downloads] page and installed using standard operating system specific installation methods.

----
== References ==
<references />

Documentation/Maemo Flasher-3.5 Tutorial/Bibliography

2010-04-09T09:04:35Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

== Bibliography ==

; 1
: Maemo SDK Virtual Image Tutorial. <tt>http://library.maemodocs.nokia.com</tt>.

----

Documentation/Maemo Flasher-3.5 Tutorial/Usage

2010-04-09T09:04:34Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Usage =

The Maemo Flasher-3.5 tool is a command line utility that supports N900 device with Fremantle 5.x platform releases and N800, N810 and N810 WiMAX Edition devices with Maemo Diablo 4.1.x platform releases.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Older Maemo devices (like Nokia 770) and older Maemo platform releases may require a specific Flasher tool from [http://tablets-dev.nokia.com/d3.php Maemo Flasher tool archive].
|}

Maemo Flasher-3.5 tool is run from a Linux, Windows or Mac OS X host computer as a command line tool, and it sends data and commands to the connected Maemo device via USB.

Among other purposes, Maemo Flasher-3.5 tool can be used to:

* flash a Maemo device with a Diablo or Fremantle FIASCO image
* flash a Maemo device (N900 only) internal memory card with an eMMC image
* unpack a FIASCO image into separate parts like kernel and rootfs images
* flash unpacked kernel or rootfs images to the Maemo device separately
* change a Maemo device to R&D mode and back to normal mode
* set and clear R&D flags for a Maemo device when in R&D mode
* boot a Maemo device with additional kernel startup parameters

All command line parameters supported by Maemo Flasher-3.5 tool together with some basic usage examples are documented in the Help.txt file available as part of the tool installation package. Maemo Flasher-3.5 tool binary gives command line help if it is run without any parameter or with <code>--set-rd-flags</code> or <code>--clear-rd-flags</code> parameters.

= Setting Maemo device to flashing mode =

Before flashing a Maemo device with a FIASCO image, it is recommended to firstly set the Maemo device into flashing mode. When you attempt to flash the Maemo device, it tries to enable flashing mode on the fly, in which case setting the device to flashing mode explicitly is not required, but there have been reports that with some host PCs this does not work, see chapters [localhost#sec:flasher-3-5-tips-and-troubleshooting [[Image:crossref.png|[*]]]] and [localhost#sec:flasher-3-5-known-issues [[Image:crossref.png|[*]]]].

For Nokia N800 and N810 with a Diablo image, flashing mode can be enabled by following these steps:

# Switch off the Maemo device (and do not use a charger).
# Attach a USB cable to the Maemo device and computer.
# Switch on the Maemo device while holding down the '''Home''' (N800) or '''Swap''' (N810) hardware button.

For Nokia N900 with a Fremantle image, flashing mode can be enabled by following these steps:

# Switch off the Maemo device.
# Press and hold down the 'u' key.
# Connect a USB cable between the Maemo device and host PC while holding down the 'u' key.
# When the USB cable is connected, it powers the Maemo device and sets it to flashing mode.
# When the USB icon appears in the upper right-hand corner, the Maemo device is in flashing mode.
# Release the 'u' key.

If performed correctly, the USB image is visible in the upper right-hand corner of the screen.

The Maemo device waits indefinitely for Flasher-3.5 input when it is in flashing mode. If flashing is tried without first setting the Maemo device to flashing mode, image flashing may fail if the Maemo device is not able to change to the flashing mode automatically.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Make sure that the device battery is fully charged before doing any sort of flashing operation because flashing fails if the battery runs out of power during the image flashing operation, and the device may not be able to charge an empty battery after a failure in flashing.
|}

= Command line options =

'''SYNOPSIS'''

Usage: <code>flasher-3.5 [OPTIONS]</code>

'''OPTIONS'''

;
: <code>-F, --fiasco=ARG</code> : Location of a FIASCO image
;
: <code>-k, --kernel=ARG</code> : Location of kernel image
;
: <code>-n, --initfs=ARG</code> : Location of initfs image
;
: <code>-r, --rootfs=ARG</code> : Location of root JFFS2 image
;
: <code>--cmt-2nd=ARG</code> : Location of CMT FIASCO 2nd image
;
: <code>--cmt-algo=ARG</code> : ocation of CMT FIASCO algorithm image
;
: <code>--cmt-mcusw=ARG</code> : Location of CMT FIASCO MCUSW image
;
: <code>--cmt-no-verify</code> : Disable verification of CMT programming
;
: <code>-x, --xloader=ARG</code> : Location of X-Loader image
;
: <code>-s, --secondary=ARG</code> : Location of NOLO secondary bootloader image
;
: <code>-2, --2nd=ARG</code> : Location of NOLO cold flasher ("2nd") image
;
: <code>-u, --unpack[=ARG]</code> : Unpack a FIASCO image
;
: <code>-f, --flash</code> : Load and flash all supplied images
;
: <code>-l, --load</code> : Only load all supplied images
;
: <code>-b, --boot[=ARG]</code> : Boot the kernel with optional cmdline
;
: <code>-R, --reboot</code> : Reboot the board (e.g. after flashing NOLO)
;
: <code>-i, --read-device-id</code> : rint out the device type
;
: <code>-S, --serial-port=ARG</code> : Serial port used for cold flashing or "usb"
;
: <code>-I, --init-port</code> : Only initialize the serial port
;
: <code>-c, --cold-flash</code> : Cold flash the device
;
: <code>-h, --hw-revision=ARG</code> : Specify product code and hardware revision
;
: <code>--enable-rd-mode</code> : Enable R&D mode on the device
;
: <code>--disable-rd-mode</code> : Disable R&D mode on the device
;
: <code>--set-rd-flags[=ARG]</code> : Set R&D mode flags on the device
;
: <code>--clear-rd-flags[=ARG]</code> : Clear R&D mode flags on the device
;
: <code>--query-rd-mode</code> : Query the device R&D mode status and flags
;
: <code>--set-hw-revision[=ARG]</code> : Set hardware revision override on device
;
: <code>--flash-only=ARG</code> : Flash only certain components
;
: <code>-U, --usb-device=ARG</code> : Specify USB device to use (bus:device address)

Valid <code>--flash-only</code> options: <code>nolo</code>, <code>kernel</code>, <code>initfs</code> and <code>rootfs</code>.

Valid <code>--set-rd-flags</code> and <code>--clear-rd-flags</code> options: <code>no-omap-wd</code>, <code>no-ext-wd</code>, <code>no-lifeguard-reset</code>, <code>serial-console</code>, <code>no-usb-timeout</code>, <code>sti-console</code>, <code>no-charging</code> and <code>force-power-key</code>.

= Usage examples =

'''To get a list of supported command line options''', run:

<code>$ flasher-3.5</code>
<code>$ flasher-3.5 --set-rd-flags</code>

If you wish to perform commands other than image flashing, then omit the <code>-R</code> option as rebooting the Maemo device may reset the given configuration change back to normal.

'''To enable R&D mode''' for Maemo device, run:

<code>$ flasher-3.5 --enable-rd-mode</code>

'''To warm flash an image''' to the Maemo device, run:

<code>$ flasher-3.5 -F <FIASCO image> -f -R</code>

Replace <FIASCO image> with the the firmware image you downloaded from Nokia. This flashes a FIASCO image to your Maemo device and reboots the device after it is completed (at which point you can unplug the USB). The procedure is the same for all other image flashing components (for example, separate kernel, rootfs and eMMC images), see the option list for details.

'''To print out Maemo device product code and product hardware revision''', run:

<code>$ flasher-3.5 -i</code>

'''To cold flash''' (needed usually when the bootloader has been changed), run:

<code>$ flasher-3.5 -c -h RX-51:<hw id> -F <FIASCO image> -f -R</code>

The code <code>RX-51</code> used in the example is the product code for the N900 device. The <code><hw id></code> is the product hardware revision, which is a 4-digit code. Both product code and hardware revision can be found from the type label of the device to be flashed. The type label is on the back of the device, underneath the battery.

'''To flash a kernel''' with separate kernel image, run:

<code>$ flasher-3.5 -k <kernel image> -f -R</code>

'''To flash just a part of the whole FIASCO image''' (for example, only rootfs), run:

<code>$ flasher-3.5 -F <FIASCO image> --flash-only=rootfs -R</code>

This flashes only the rootfs from the <FIASCO image> and reboot the device.

'''To access to the individual parts of the FIASCO image''', run:

<code>$ flasher-3.5 -F <FIASCO image> -u</code>

which expands <FIASCO image> to your current directory.

= Tips and Troubleshooting =

* If you get a "Permission denied" error, then make sure you have execution rights to the Flasher-3.5 binary executable.
* You need to have administrator rights or run command with sudo in Linux if you get errors like this: Error claiming USB interface: Operation not permitted
* It may help to connect the USB cable directly to the computer USB ports, avoiding the use of a hub. Using the USB ports in the back of a computer can also work better than using those in the front.
* Flash always the FIASCO image first and after that the latest available eMMC image, if needed. The eMMC image does not need to be flashed every time when a new FIASCO image is flashed. Flashing the eMMC image also overwrites all data from the internal memory card.
* If warm flashing fails, try to switch off the power from the Maemo device, remove the USB cable and try again from the beginning.
* If cold flashing fails, try to warm flash the Maemo device first using the same FIASCO image. After that try cold flashing again.
* If Maemo Flasher-3.5 is not supported on your operating system you can try to install Maemo SDK Virtual Image from [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php Maemo Development Environment Downloads] page and flash Maemo device from Virtual Image (which includes Ubuntu). This may or may not work for you depending on how well virtualization technology you use supports USB on your hardware.

= Known issues =

This is a list of known issues found from Maemo Flasher-3.5 final release.

* Maemo Flasher-3.5 does not work with 64-bit operating systems. Workaround is to install Maemo SDK Virtual Image and run Maemo Flasher-3.5 from image.
* Maemo Flasher-3.5 does not work with Mandriva 2010 distro because Flasher-3.5 is not able to locate the correct USB address and timeouts. Workaround is to install Maemo SDK Virtual Image and run Maemo Flasher-3.5 from image.
* On Windows host PC if Nokia PC Suite has been installed to the environment once Windows has started also PC Suite starts running. If Nokia PC Suite is running when N900 is plugged in to the PC with USB cable and with the 'u' key held down, Nokia PC Suite gives an error message and Flasher-3.5 does not see the device. Workaround is to exit Nokia PC Suite before plugging in N900 with USB cable and starting Flasher-3.5.

Documentation/Maemo Eclipse Tutorial/Using PluThon

2010-04-09T09:04:32Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Using PluThon =

PluThon supports only Python projects. This chapter briefly shows hot to create Python projects and applications and run, test and debug Python applications with Maemo device.

PluThon requires Python installed on host PC and Maemo Device. See PluThon installation chapters for detailed information how to install PlutThon itself and needed Python development environments. PC Connectivity is needed to connect Maemo Device to host PC and PluThon. See PC Connectivity documentation for details how to install and configure Maemo PC Connectivity to the Maemo Device and Host PC Connectivity to the host PC you are running PluThon Eclipse environment.

Ensure that you can connect to the Maemo device from the host PC (that PC Connectivity has been properly installed and configured) before creating your first project with PluThon.

= Creating PluThon Python projects =

Create new PluThon project from '''File menu > New > PluThon Project''', figure [[#fig:pluthon_usage_project_01_new|7.1]].

{| summary="New Project Menu"
|+ align="BOTTOM" |'''Figure 7.1:''' New Project Menu
|-
|
[[Image:project-01-new.png|Image project-01-new]]
|}

== PluThon Project Templates ==

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

Select any template under '''Examples'''. Some of the templates are only for Diablo device (N800 or N810) and others for Fremantle (N900), figure [[#fig:pluthon_usage_project_03_template|7.2]].

{| summary="PluThon Project Template"
|+ align="BOTTOM" |'''Figure 7.2:''' PluThon Project Template
|-
|
[[Image:project-03-template.png|Image project-03-template]]
|}

== PluThon Project Target ==

Select your connection to the device from the list. Default IP addresses are the same as PC Connectivity uses as default. The connection must be enabled from device PC Connectivity. See the PC Connectivity documentation for more information.

If you only use SSH connection to your device, or you have other IP values in your PC Connectivity properties, you can configure the connection here by right-clicking connection and selecting '''configure'''. Then you need to set '''Host name''' and '''Default User ID''', figures [[#fig:pluthon_usage_project_04_target|7.3]] and [[#fig:pluthon_usage_configure_connection|7.4]].

{| summary="PluThon Project Target"
|+ align="BOTTOM" |'''Figure 7.3:''' PluThon Project Target
|-
|
[[Image:project-04-target.png|Image project-04-target]]
|}

{| summary="PluThon Project Target"
|+ align="BOTTOM" |'''Figure 7.4:''' PluThon Project Target
|-
|
[[Image:configure-connection.png|Image configure-connection]]
|}

You can configure connections afterwards from '''Window > Preferences > Maemo > Installed Targets''' or use Remote Systems view '''Window > Show View > Other > Remote Systems > Remote Systems'''.

== PluThon Project Metadata ==

'''Basic Settings''' page defines some basic variables used by the selected template. You can insert requested information into fields or leave default values, figure [[#fig:pluthon_usage_project_05_metadata|7.5]].

{| summary="PluThon Project Configuration"
|+ align="BOTTOM" |'''Figure 7.5:''' PluThon Project Configuration
|-
|
[[Image:project-05-metadata.png|Image project-05-metadata]]
|}

== PluThon Project Interpreter Configuration ==

Python configuration is done on the last page. If existing Python configuration is not found, a wizard suggests creating a new configuration.

Leave all values as default and press the '''Finish''' button to create project, figure [[#fig:pluthon_usage_project_06_configuration|7.6]].

{| summary="PluThon Project Configuration"
|+ align="BOTTOM" |'''Figure 7.6:''' PluThon Project Configuration
|-
|
[[Image:project-06-configuration.png|Image project-06-configuration]]
|}

If there were no previous configurations for your project, ESbox will ask you to create new configuration. Select '''Yes''' to create one, figure [[#fig:pluthon_usage_project_07_interpreter_dialog|7.7]].

{| summary="Python Interpreter Dialog"
|+ align="BOTTOM" |'''Figure 7.7:''' Python Interpreter Dialog
|-
|
[[Image:project-07-interpreter-dialog.png|Image project-07-interpreter-dialog]]
|}

For the Python interpreter configuration you can select all Python paths and confirm the addition with '''OK''' button, figure [[#fig:pluthon_usage_project_08_interpreter_paths|7.8]].

{| summary="Python Interpreter Path Configuration"
|+ align="BOTTOM" |'''Figure 7.8:''' Python Interpreter Path Configuration
|-
|
[[Image:project-08-interpreter-paths.png|Image project-08-interpreter-paths]]
|}

== Validating PluThon Project Packages on Maemo Device ==

PluThon suggests package validation when a new project is created. Answer '''Yes''' to package validations, figure [[#fig:pluthon_usage_project_09_validate_dialog|7.9]].

{| summary="Validate Packages Dialog"
|+ align="BOTTOM" |'''Figure 7.9:''' Validate Packages Dialog
|-
|
[[Image:project-09-validate-dialog.png|Image project-09-validate-dialog]]
|}

PluThon installs the required dependencies into the Maemo device after you press '''Finnish''' button on Package Validation Wizard, figure [[#fig:pluthon_usage_project_10_validate_wizard|7.10]].

{| summary="Validate Packages Wizard"
|+ align="BOTTOM" |'''Figure 7.10:''' Validate Packages Wizard
|-
|
[[Image:project-10-validate-wizard.png|Image project-10-validate-wizard]]
|}

Accept any packages PluThon suggests to install and close validation after the packages have been installed.

Package validation can be invoked from menu afterwards. Select '''Project > Project Menu > Validate installed packages'''.

During a validation project, dependencies are scanned from projects using Python package imports from source files.

= Running Python Application on Maemo Device =

In order to run applications on Maemo devices, the Maemo PC Connectivity package must be installed on the device and the Host PC Connectivity package for the host PC. See the PluThon installation chapters for more information.

You can run Python applications with PluThon by right-clicking a project and choosing '''Run As > PluThon Application''', figure [[#fig:pluthon_usage_run_01_run_as|7.11]].

{| summary="Run as PluThon Application"
|+ align="BOTTOM" |'''Figure 7.11:''' Run as PluThon Application
|-
|
[[Image:run-01-run-as.png|Image run-01-run-as]]
|}

Next, select the Python file to be run (do not select setup.py because it is used only for Debian package creation), figure [[#fig:pluthon_usage_run_02_script|7.12]].

{| summary="Select Executable"
|+ align="BOTTOM" |'''Figure 7.12:''' Select Executable
|-
|
[[Image:run-02-script.png|Image run-02-script]]
|}

Then select the download method as Copy Programs (SSH) (as SBRSH requires configuration), figure [[#fig:pluthon_usage_run_03_download|7.13]].

{| summary="Select Download Method"
|+ align="BOTTOM" |'''Figure 7.13:''' Select Download Method
|-
|
[[Image:run-03-download.png|Image run-03-download]]
|}

You can now see the program running on the Maemo device.

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

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' The x11vnc service must be installed on the Maemo device either separately (apt-get install x11vnc) or as part of Maemo PC Connectivity.
|}

= Debugging PluThon Application on Maemo Device =

In order to debug the project, set at least one breakpoint into one of the source files where you want to start debugging. Open the source file and place the breakpoint at some position by right-clicking the left source side panel and choosing '''Add Breakpoint''', figure [[#fig:pluthon_usage_debug_02_add_breakpoint|7.14]].

{| summary="Add Breakpoint"
|+ align="BOTTOM" |'''Figure 7.14:''' Add Breakpoint
|-
|
[[Image:debug-02-add-breakpoint.png|Image debug-02-add-breakpoint]]
|}

Launch your project in debug mode by right-clicking project and choosing '''Debug As > PluThon Application''' and accept changing to debug perspective, figure [[#fig:pluthon_usage_debug_01_menu|7.15]].

{| summary="Debug as PluThon Application"
|+ align="BOTTOM" |'''Figure 7.15:''' Debug as PluThon Application
|-
|
[[Image:debug-01-menu.png|Image debug-01-menu]]
|}

From the debug perspective, you can stop and continue execution, step lines, inspect variables, and so on. See Figures [[#fig:pluthon_usage_python_debug_03_perspective|7.16]] and [[#fig:pluthon_usage_debug_04_variables|7.17]].

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' You can switch back and forth between perspectives from top-right corner.
|}

{| summary="Debug View"
|+ align="BOTTOM" |'''Figure 7.16:''' Debug View
|-
|
[[Image:debug-03-debug-view.png|Image debug-03-debug-view]]
|}

{| summary="Variables View"
|+ align="BOTTOM" |'''Figure 7.17:''' Variables View
|-
|
[[Image:debug-04-variables-view.png|Image debug-04-variables-view]]
|}

= Debian Packaging PluThon Project =

== Generating Setup Script ==

The setup script (setup.py) is used to create the Debian installation package for Python projects.

In setup script generator you need to define metadata, packages, executables and datafiles. This information is then used to create setup.py script for the project, figure [[#fig:pluthon_usage_debian_01_setup_wizard|7.18]].

{| summary="Debian Package Setup Wizard"
|+ align="BOTTOM" |'''Figure 7.18:''' Debian Package Setup Wizard
|-
|
[[Image:debian-01-setup-wizard.png|Image debian-01-setup-wizard]]
|}

PluThon provides an automated wizard for creating Debian installation packages with this script. You can create the script from '''File > New > Other > PyDev > Setup Script''', figure [[#fig:pluthon_usage_debian_02_setup_wizard|7.19]].

{| summary="Debian Package Setup Project"
|+ align="BOTTOM" |'''Figure 7.19:''' Debian Package Setup Project
|-
|
[[Image:debian-02-setup-project.png|Image debian-02-setup-project]]
|}

For the setup.py script you need to define certain metadata for the installation pacakge, figure [[#fig:pluthon_usage_debian_03_setup_parameters|7.20]].

{| summary="Debian Package Setup Parameters"
|+ align="BOTTOM" |'''Figure 7.20:''' Debian Package Setup Parameters
|-
|
[[Image:debian-03-setup-parameters.png|Image debian-03-setup-parameters]]
|}

Information about packages included in the installation package, figure [[#fig:pluthon_usage_debian_04_setup_package|7.21]].

{| summary="Debian Package Setup Packages"
|+ align="BOTTOM" |'''Figure 7.21:''' Debian Package Setup Packages
|-
|
[[Image:debian-04-setup-package.png|Image debian-04-setup-package]]
|}

Information about extra resources such as modules, scripts and data files included in the installation package, figure [[#fig:pluthon_usage_debian_05_setup_data|7.22]].

{| summary="Debian Package Setup Data"
|+ align="BOTTOM" |'''Figure 7.22:''' Debian Package Setup Data
|-
|
[[Image:debian-05-setup-data.png|Image debian-05-setup-data]]
|}

You can find more information about the Python setup script from [http://docs.python.org/distutils/setupscript.html Python distutils documentation].

== Create Debian Installation Package ==

You can export a project to the Debian installation package from '''File > Export > PluThon > Export to Debian Package'''. This command requires that setup.py script has been defined for the project.

{| summary="Export to Debian Package"
|+ align="BOTTOM" |'''Figure 7.23:''' Export to Debian Package
|-
|
[[Image:debian-08-export-setup.png|Image debian-08-export-setup]]
|}

In Debian package export you only need to select the project and setup script. The package is created on the Maemo device using bdist-maemo distutils packages, figure [[#fig:pluthon_usage_debian_08_export_setup|7.23]].

== Install Debian Package to Maemo Device ==

To install a created Debian package to the Maemo device, right-click project and select '''Install Debian Package on Device''', figure [[#fig:pluthon_usage_debian_06_install_menu|7.24]].

{| summary="Install Debian Package Menu"
|+ align="BOTTOM" |'''Figure 7.24:''' Install Debian Package Menu
|-
|
[[Image:debian-06-install-menu.png|Image debian-06-install-menu]]
|}

From the '''Install Debian Package''' wizard select '''Browse''' and set '''Package location''' to created package, select the correct connection and install using the '''Finish''' button, figure [[#fig:pluthon_usage_debian_07_install|7.25]].

{| summary="Install Debian Package Wizard"
|+ align="BOTTOM" |'''Figure 7.25:''' Install Debian Package Wizard
|-
|
[[Image:debian-07-install.png|Image debian-07-install]]
|}

Documentation/Maemo Eclipse Tutorial/Getting Started with Maemo Eclipse

2010-04-09T09:04:31Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= 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 [[#fig:eclipse_tutorial_select_workspace|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.

{| summary="Selecting a workspace folder"
|+ align="BOTTOM" |'''Figure 2.1:''' Selecting a workspace folder
|-
|
[[Image:select_workspace.png|Image select_workspace]]
|}

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.

{| summary="Properties view"
|+ align="BOTTOM" |'''Figure 2.2:''' Properties view
|-
|
[[Image:properties_view.png|Image properties_view]]
|}

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 [[#fig:eclipse_tutorial_workbench|2.3]] shows the most important Workbench components.

{| summary="Basic Eclipse elements"
|+ align="BOTTOM" |'''Figure 2.3:''' Basic Eclipse elements
|-
|
[[Image:workbench.png|Image workbench]]
|}

The basic elements of the environment include:

# 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.
# 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.
# 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.
# Short Cut Bar: a set of icons that enables the user to access different perspectives quickly.
# Menu Bar: a set of content-sensitive actions that enables the execution of some predefined function.
# 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.
# 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'''.

{| summary="Preferences dialog"
|+ align="BOTTOM" |'''Figure 2.4:''' Preferences dialog
|-
|
[[Image:preferences_dialog.png|Image preferences_dialog]]
|}

= 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-`<nowiki>: (in C/C++ editor) swap header and source </nowiki>
* Ctrl-3<nowiki>: find almost any user interface in your installation </nowiki>

= 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'''<nowiki>: in the event of bugs, navigate here and enable </nowiki>'''Log commands'''. The command log is important for diagnosing problems.
* '''Window -> Preferences -> Maemo -> Installed Targets'''<nowiki>: 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. </nowiki>
* '''File -> New -> Other -> Maemo Installers'''<nowiki>: the wizards for installing a full development environment, including a virtual disk image for ESbox are here. </nowiki>

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 [[#fig:eclipse_tutorial_help_menu|2.5]] or using the '''Help view''' as shown in figure [[#fig:eclipse_tutorial_help_search|2.6]].

{| summary="Help in a separate Window"
|+ align="BOTTOM" |'''Figure 2.5:''' Help in a separate Window
|-
|
[[Image:help_menu.png|Image help_menu]]
|}

{| summary="Help in the Help View"
|+ align="BOTTOM" |'''Figure 2.6:''' Help in the Help View
|-
|
[[Image:help_search.png|Image help_search]]
|}

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

{| summary="ESbox Help"
|+ align="BOTTOM" |'''Figure 2.7:''' ESbox Help
|-
|
[[Image:help_esbox.png|Image help_esbox]]
|}

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 [[#fig:eclipse_tutorial_help_view_esbox|2.8]]. All related topics are returned. This search can also be done in the separate '''Help Window'''.

{| summary="Help View"
|+ align="BOTTOM" |'''Figure 2.8:''' Help View
|-
|
[[Image:help_view_esbox.png|Image help_view_esbox]]
|}

PluThon Help Documentation can be accessed in the same way as ESbox help as shown in figure [[#fig:eclipse_tutorial_help_pluthon|2.9]].

{| summary="PluThon Help Documentation"
|+ align="BOTTOM" |'''Figure 2.9:''' PluThon Help Documentation
|-
|
[[Image:help_pluthon.png|Image help_pluthon]]
|}

Documentation/Maemo Eclipse Tutorial

2010-04-09T09:04:31Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

{| width="100%"
|
Nokia Corporation = MAEMO ECLIPSE TUTORIAL =<div class="author_info">'''maemo.org''''''18 February 2010'''</div>
|}

----

<div class="margins">

* [[{{PAGENAME}}/Preface|Preface]]
* [[{{PAGENAME}}/Glossary|Glossary]]
* [[{{PAGENAME}}/Introduction|Introduction]]
* [[{{PAGENAME}}/Getting Started with Maemo Eclipse|Getting Started with Maemo Eclipse]]
* [[{{PAGENAME}}/Installation Methods|Installation Methods]]
* [[{{PAGENAME}}/Installing PluThon|Installing PluThon]]
* [[{{PAGENAME}}/Installing ESbox|Installing ESbox]]
* [[{{PAGENAME}}/Setting Up ESbox|Setting Up ESbox]]
* [[{{PAGENAME}}/Using PluThon|Using PluThon]]
* [[{{PAGENAME}}/Using ESbox|Using ESbox]]
* [[{{PAGENAME}}/Eclipse Tracing|Eclipse Tracing]]
* [[{{PAGENAME}}/Eclipse Memory Profiling|Eclipse Memory Profiling]]
* [[{{PAGENAME}}/Eclipse Performance Profiling|Eclipse Performance Profiling]]
* [[{{PAGENAME}}/Bibliography|Bibliography]]

</div>

----

Documentation/Maemo Eclipse Tutorial/Using ESbox

2010-04-09T09:04:30Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= 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).

= Creating C/C++ and Qt4 Projects =

== 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 [[#fig:esbox_usage_project_new|8.1]].

* C > C Maemo Project
* C++ > C++ Maemo Project

For Qt4 projects, select C++ project.

{| summary="New Project Menu"
|+ align="BOTTOM" |'''Figure 8.1:''' New Project Menu
|-
|
[[Image:project-Python-new.png|Image project-Python-new]]
|}

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

{| summary="New C/C++ Project"
|+ align="BOTTOM" |'''Figure 8.2:''' New C/C++ Project
|-
|
[[Image:c-01-projects.png|Image c-01-projects]]
|}

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

{| summary="C/C++ Project Template"
|+ align="BOTTOM" |'''Figure 8.3:''' C/C++ Project Template
|-
|
[[Image:c-02-templates.png|Image c-02-templates]]
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' '''Maemo 4''' templates are only for Diablo targets and '''Maemo 5''' templates for Fremantle. Select the correct template depending on your installation.
|}

== 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 [[#fig:esbox_usage_c_03_targets|8.4]]. You can change the targets after you have created the project.

{| summary="C/C++ Project Target"
|+ align="BOTTOM" |'''Figure 8.4:''' C/C++ Project Target
|-
|
[[Image:c-03-targets.png|Image c-03-targets]]
|}

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.

== 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 [[#fig:esbox_usage_c_04_metadata|8.5]].

{| summary="C/C++ Project Metadata"
|+ align="BOTTOM" |'''Figure 8.5:''' C/C++ Project Metadata
|-
|
[[Image:c-04-metadata.png|Image c-04-metadata]]
|}

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

== Validating C/C++ and Qt4 Project Packages for Maemo SDK ==

When you have created a new project, ESbox suggests package validation, figure [[#fig: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'''.

{| summary="Validate Packages Dialog"
|+ align="BOTTOM" |'''Figure 8.6:''' Validate Packages Dialog
|-
|
[[Image:c-05-validate.png|Image c-05-validate]]
|}

ESbox installs all the required dependencies for your project for the selected targets, if they are not installed already, figure [[#fig:esbox_usage_c_06_validate_wizard|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.

{| summary="Validate Packages Wizard"
|+ align="BOTTOM" |'''Figure 8.7:''' Validate Packages Wizard
|-
|
[[Image:c-06-validate-wizard.png|Image c-06-validate-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_CONFIG_CHECK macros in configure.ac
* Makefile projects: default metapackages for the project type and libraries detected through <code>pkg-config</code> invocations

= 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).

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

{| summary="Set C/C++ Project Target"
|+ align="BOTTOM" |'''Figure 8.8:''' Set C/C++ Project Target
|-
|
[[Image:c-07-set-target.png|Image c-07-set-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 [[#fig:esbox_usage_c_08_run_as|8.9]].

{| summary="Run C/C++ Project as Local Application"
|+ align="BOTTOM" |'''Figure 8.9:''' Run C/C++ Project as Local Application
|-
|
[[Image:c-08-run-as.png|Image c-08-run-as]]
|}

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 [[#fig:esbox_usage_c_09_result|8.10]].

{| summary="C/C++ Project Local Launch Result"
|+ align="BOTTOM" |'''Figure 8.10:''' C/C++ Project Local Launch Result
|-
|
[[Image:c-09-result.png|Image c-09-result]]
|}

= 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 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 [[#fig:esbox_usage_c_remote_01_manage|8.11]].

{| summary="C/C++ Project Manage Target Menu"
|+ align="BOTTOM" |'''Figure 8.11:''' C/C++ Project Manage Target Menu
|-
|
[[Image:c-remote-01-manage.png|Image c-remote-01-manage]]
|}

Set the target to DIABLO_ARMEL or FREMANTLE_ARMEL, figure [[#fig:esbox_usage_c_remote_02_targets|8.12]].

{| summary="C/C++ Project Manage Targets"
|+ align="BOTTOM" |'''Figure 8.12:''' C/C++ Project Manage Targets
|-
|
[[Image:c-remote-02-targets.png|Image c-remote-02-targets]]
|}

Right-click the project, select '''Build Configurations > Set Active''' and activate DIABLO_ARMEL (Debug) or FREMANTLE_ARMEL (Debug), figure [[#fig:esbox_usage_c_remote_03_set_target|8.13]].

{| summary="Set C/C++ Project Target"
|+ align="BOTTOM" |'''Figure 8.13:''' Set C/C++ Project Target
|-
|
[[Image:c-remote-03-set-target.png|Image c-remote-03-set-target]]
|}

== 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 [[#fig:esbox_usage_c_remote_04_validate_device|8.14]].

{| summary="Validate Packages Menu"
|+ align="BOTTOM" |'''Figure 8.14:''' Validate Packages Menu
|-
|
[[Image:c-remote-04-validate-device.png|Image c-remote-04-validate-device]]
|}

On the '''Target Selection''' page, select the correct Maemo device connection and ARMEL target, Figure [[#fig:esbox_usage_c_remote_05_validate_targets|8.15]].

{| summary="Validate Package Targets"
|+ align="BOTTOM" |'''Figure 8.15:''' Validate Package Targets
|-
|
[[Image:c-remote-05-validate-targets.png|Image c-remote-05-validate-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'''.

== 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 [[#fig:esbox_usage_c_remote_06_run|8.16]].

{| summary="Run C/C++ Project as Remote Maemo Application"
|+ align="BOTTOM" |'''Figure 8.16:''' Run C/C++ Project as Remote Maemo Application
|-
|
[[Image:c-remote-06-run.png|Image c-remote-06-run]]
|}

Select SSH as the connection type (using the SBRSH connection type requires additional configuration), figure [[#fig:esbox_usage_c_remote_07_use_ssh|8.17]].

{| summary="Connection Type Dialog"
|+ align="BOTTOM" |'''Figure 8.17:''' Connection Type Dialog
|-
|
[[Image:c-remote-07-use-ssh.png|Image c-remote-07-use-ssh]]
|}

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

{| summary="Select Device Connection Dialog"
|+ align="BOTTOM" |'''Figure 8.18:''' Select Device Connection Dialog
|-
|
[[Image:c-remote-08-select-connection.png|Image c-remote-08-select-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:dialog-information.png]]
| '''Note:''' 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.
|}

= 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 [[#fig:esbox_usage_c_debug_01_breakpoint|8.19]].

{| summary="Adding Breakpoint to C/C++ Source File"
|+ align="BOTTOM" |'''Figure 8.19:''' Adding Breakpoint to C/C++ Source File
|-
|
[[Image:c-debug-01-breakpoint.png|Image c-debug-01-breakpoint]]
|}

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 [[#fig:esbox_usage_c_debug_02_debug|8.20]].

{| summary="Debug as Maemo Application Menu"
|+ align="BOTTOM" |'''Figure 8.20:''' Debug as Maemo Application Menu
|-
|
[[Image:c-debug-02-debug.png|Image c-debug-02-debug]]
|}

In the debug perspective, you can stop and continue the execution, step lines, inspect variables, and so on. See Figures [[#fig:esbox_usage_c_debug_03_perspective|8.21]] and [[#fig:esbox_usage_c_debug_04_variables|8.22]].

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' You can switch back and forth between perspectives by selecting from the top right corner.
|}

{| summary="C/C++ Project Debug View"
|+ align="BOTTOM" |'''Figure 8.21:''' C/C++ Project Debug View
|-
|
[[Image:c-debug-03-perspective.png|Image c-debug-03-perspective]]
|}

{| summary="Inspect C/C++ Variables"
|+ align="BOTTOM" |'''Figure 8.22:''' Inspect C/C++ Variables
|-
|
[[Image:c-debug-04-variables.png|Image c-debug-04-variables]]
|}

= Creating Python Projects =

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

== 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 [[#fig:esbox_usage_project_python_new|8.23]].

{| summary="New Project Menu"
|+ align="BOTTOM" |'''Figure 8.23:''' New Project Menu
|-
|
[[Image:project-Python-new.png|Image project-Python-new]]
|}

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

{| summary="Python Project Template"
|+ align="BOTTOM" |'''Figure 8.24:''' Python Project Template
|-
|
[[Image:python-01-template.png|Image python-01-template]]
|}

== Python Targets ==

Select DIABLO_X86 or FREMANTLE_X86 as the target, figure [[#fig:esbox_usage_python_02_target|8.25]].

{| summary="Python Project Target"
|+ align="BOTTOM" |'''Figure 8.25:''' Python Project Target
|-
|
[[Image:python-02-target.png|Image python-02-target]]
|}

== 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 [[#fig:esbox_usage_python_03_metadata|8.26]].

{| summary="Python Project Metadata"
|+ align="BOTTOM" |'''Figure 8.26:''' Python Project Metadata
|-
|
[[Image:python-03-metadata.png|Image python-03-metadata]]
|}

== 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 [[#fig:esbox_usage_python_04_grammar|8.27]].

{| summary="Python Project Configuration"
|+ align="BOTTOM" |'''Figure 8.27:''' Python Project Configuration
|-
|
[[Image:python-04-grammar.png|Image python-04-grammar]]
|}

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 [[#fig:esbox_usage_python_05_path|8.28]].

{| summary="Python Project Interpreter Paths"
|+ align="BOTTOM" |'''Figure 8.28:''' Python Project Interpreter Paths
|-
|
[[Image:python-05-path.png|Image python-05-path]]
|}

== Validating Python Project Packages ==

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

{| summary="Validate Packages"
|+ align="BOTTOM" |'''Figure 8.29:''' Validate Packages
|-
|
[[Image:c-05-validate.png|Image c-05-validate]]
|}

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

{| summary="Validate Packages Wizard"
|+ align="BOTTOM" |'''Figure 8.30:''' Validate Packages Wizard
|-
|
[[Image:c-06-validate-wizard.png|Image c-06-validate-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.

= 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 [[#fig:esbox_usage_python_06_properties|8.31]].

{| summary="Python Project Properties"
|+ align="BOTTOM" |'''Figure 8.31:''' Python Project Properties
|-
|
[[Image:python-06-properties.png|Image python-06-properties]]
|}

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

{| summary="Python Project Build Configuration"
|+ align="BOTTOM" |'''Figure 8.32:''' Python Project Build Configuration
|-
|
[[Image:python-07-configuration.png|Image python-07-configuration]]
|}

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

{| summary="Python Project Run as Local Application"
|+ align="BOTTOM" |'''Figure 8.33:''' Python Project Run as Local Application
|-
|
[[Image:python-08-run-as.png|Image python-08-run-as]]
|}

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 [[#fig:esbox_usage_python_09_run_file|8.34]].

{| summary="Python Project Select File on Launch"
|+ align="BOTTOM" |'''Figure 8.34:''' Python Project Select File on Launch
|-
|
[[Image:python-09-run-file.png|Image python-09-run-file]]
|}

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 [[#fig:esbox_usage_python_10_result|8.35]].

{| summary="Python Project Local Launch Result"
|+ align="BOTTOM" |'''Figure 8.35:''' Python Project Local Launch Result
|-
|
[[Image:python-10-result.png|Image python-10-result]]
|}

= 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 [[#fig:esbox_usage_python_remote_02_target|8.36]].

{| summary="Select Python Project Target"
|+ align="BOTTOM" |'''Figure 8.36:''' Select Python Project Target
|-
|
[[Image:python-remote-02-target.png|Image python-remote-02-target]]
|}

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

== 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 [[#fig:esbox_usage_python_c_remote_04_validate_device|8.37]].

{| summary="Validate Packages Menu"
|+ align="BOTTOM" |'''Figure 8.37:''' Validate Packages Menu
|-
|
[[Image:c-remote-04-validate-device.png|Image c-remote-04-validate-device]]
|}

On the '''Target Selection''' page, select the correct Maemo device connection and ARMEL target, Figure [[#fig:esbox_usage_python_c_remote_05_validate_targets|8.38]].

{| summary="Validate Package Targets"
|+ align="BOTTOM" |'''Figure 8.38:''' Validate Package Targets
|-
|
[[Image:c-remote-05-validate-targets.png|Image c-remote-05-validate-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.

== 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 [[#fig:esbox_usage_python_remote_03_run|8.39]].

{| summary="Python Project Run as Remote Application"
|+ align="BOTTOM" |'''Figure 8.39:''' Python Project Run as Remote Application
|-
|
[[Image:python-remote-03-run.png|Image python-remote-03-run]]
|}

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:dialog-information.png]]
| '''Note:''' 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.
|}

= 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 [[#fig:esbox_usage_python_debug_01_breakpoint|8.40]].

{| summary="Add Breakpoint to Python Project"
|+ align="BOTTOM" |'''Figure 8.40:''' Add Breakpoint to Python Project
|-
|
[[Image:python-debug-01-breakpoint.png|Image python-debug-01-breakpoint]]
|}

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 [[#fig:esbox_usage_python_debug_02_debug|8.41]].

{| summary="Debug Python Project as"
|+ align="BOTTOM" |'''Figure 8.41:''' Debug Python Project as
|-
|
[[Image:python-debug-02-debug.png|Image python-debug-02-debug]]
|}

In the debug perspective, you can stop and continue the execution, step lines, inspect variables, and so on. See Figures [[#fig:esbox_usage_python_debug_03_perspective|8.42]] and [[#fig:esbox_usage_python_debug_04_variables|8.43]].

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' You can switch back and forth between perspectives by selecting from the top right corner.
|}

{| summary="Python Debug View"
|+ align="BOTTOM" |'''Figure 8.42:''' Python Debug View
|-
|
[[Image:python-debug-03-perspective.png|Image python-debug-03-perspective]]
|}

{| summary="Inspect Python Variables"
|+ align="BOTTOM" |'''Figure 8.43:''' Inspect Python Variables
|-
|
[[Image:python-debug-04-variables.png|Image python-debug-04-variables]]
|}

= 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.

== 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 [http://www.debian.org/doc/maint-guide/ Debian New Maintainers' Guide]

== 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.

== 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'''.

= Importing Projects from Repository =

== Background ==

This feature assumes you know a little bit about the workings of Debian packages. If not, the full details are in [http://www.debian.org/doc/FAQ/ch-pkg_basics.en.html The Debian GNU/Linux FAQ; Chapter 7 - Basics of the Debian package management system].

== 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>).

== Source package structure ==

The sources for a package come usually in three files: a ''control file'' (<nowiki>*.dsc</nowiki>), an ''archive'' (<nowiki>*.tar.gz</nowiki> or <nowiki>*.tar.bz2</nowiki>), and a ''patch'' (<nowiki>*.diff.gz</nowiki>). 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 [http://www.debian.org/doc/debian-policy/ch-source.html 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.

== Using the Wizard ==

Find the wizard under '''File > Import > ESbox > Project from Debian Repository''', figure [[#fig:esbox_usage_import_package_wizard|8.44]].

{| summary="Import"
|+ align="BOTTOM" |'''Figure 8.44:''' Import
|-
|
[[Image:ImportPackageWizard.png|Image ImportPackageWizard]]
|}

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

{| summary="Import ESbox Project from Repository - Select Package"
|+ align="BOTTOM" |'''Figure 8.45:''' Import ESbox Project from Repository - Select Package
|-
|
[[Image:ImportPackageSelect.png|Image ImportPackageSelect]]
|}

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

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' 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 [[#fig:esbox_usage_import_package_project|8.46]].

{| summary="Import ESbox Project from Repository - Project Configuration"
|+ align="BOTTOM" |'''Figure 8.46:''' Import ESbox Project from Repository - Project Configuration
|-
|
[[Image:ImportPackageProject.png|Image ImportPackageProject]]
|}

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

{|
|+ align="BOTTOM" |'''Figure 8.47:''' Import ESbox Project from Repository - Fetching and Importing, proxy
|-
|
[[Image:ImportPackageFetch0.png|Image ImportPackageFetch0]]
|}

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

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

{|
|+ align="BOTTOM" |'''Figure 8.48:''' Import ESbox Project from Repository - Fetching and Importing, fetching
|-
|
[[Image:ImportPackageFetch1.png|Image ImportPackageFetch1]]
|}

If the fetch fails â 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 [[#fig:esbox_usage_import_package_convert1|8.49]].

{| summary="Import ESbox Project from Repository - Convert Project"
|+ align="BOTTOM" |'''Figure 8.49:''' Import ESbox Project from Repository - Convert Project
|-
|
[[Image:ImportPackageConvert1.png|Image ImportPackageConvert1]]
|}

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 [[#fig:esbox_usage_import_package_convert2|8.50]].

{| summary="Import ESbox Project from Repository - Convert Project, compressed archive"
|+ align="BOTTOM" |'''Figure 8.50:''' Import ESbox Project from Repository - Convert Project, compressed archive
|-
|
[[Image:ImportPackageConvert2.png|Image ImportPackageConvert2]]
|}

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 [[#fig:esbox_usage_import_package_convert3|8.51]].

{| summary="Import ESbox Project from Repository - Convert Project, rule selection"
|+ align="BOTTOM" |'''Figure 8.51:''' Import ESbox Project from Repository - Convert Project, rule selection
|-
|
[[Image:ImportPackageConvert3.png|Image ImportPackageConvert3]]
|}

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 [[#fig:esbox_usage_import_package_convert3b|8.52]].

{| summary="Import ESbox Project from Repository - Convert Project, building"
|+ align="BOTTOM" |'''Figure 8.52:''' Import ESbox Project from Repository - Convert Project, building
|-
|
[[Image:ImportPackageConvert3b.png|Image ImportPackageConvert3b]]
|}

Once the configuration step has been run, the conversion page updates its guess about the project, figure [[#fig:esbox_usage_import_package_convert4|8.53]].

{| summary="Import ESbox Project from Repository - Convert Project, updated"
|+ align="BOTTOM" |'''Figure 8.53:''' Import ESbox Project from Repository - Convert Project, updated
|-
|
[[Image:ImportPackageConvert4.png|Image ImportPackageConvert4]]
|}

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.

== Related Topics ==

* [https://garage.maemo.org/svn/esbox/trunk/org.maemo.esbox.help/html/tasks/ConfiguringCppBuild.html Configuring C/C++ Builds]
* [https://garage.maemo.org/svn/esbox/trunk/org.maemo.esbox.help/html/tasks/ConvertingESboxProjects.html Converting ESbox Projects]

Documentation/Maemo Eclipse Tutorial/Glossary

2010-04-09T09:04:30Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Glossary =

; '''ABI'''
: Application Binary Interface, providing object code level compatibility.
; '''API'''
: Application Programming Interface, providing source code level compatibility.
; '''applet'''
: A small application that integrates to ''Hildon Desktop''.
; '''ARMEL'''
: A name that e.g. Debian uses for the little endian ARM EABI (''ABI'' for the ARM architecture).
; '''Bluetooth'''
: is an open wireless protocol for exchanging data over short distances (using short length radio waves) from fixed and mobile devices, creating personal area networks (PANs).
; '''CDT'''
: Eclipse C/C++ Development Toolkit.
; '''CIFS'''
: Common Internet File System (also known as Server Message Block, SMB) operates as an application-layer network protocol mainly used to provide shared access to files, printers, serial ports, and miscellaneous communications between nodes on a network.
; '''CVS'''
: Concurrent Versions System.
; '''devkit'''
: The part of ''Maemo SDK'' that contains software development tools. Maemo SDK contains multiple devkits.
; '''DHCP'''
: Dynamic Host Configuration Protocol is a computer networking protocol used by hosts (DHCP clients) to retrieve IP address assignments and other configuration information.
; '''DSDP'''
: Eclipse Device Software Development Platform.
; '''DSF'''
: Eclipse Debugger Services Framework.
; '''ECF'''
: Eclipse Communication Framework.
; '''ESbox'''
: Eclipse product implementing integration between Eclipse IDE and Maemo SDK.
; '''GDB'''
: GNU Project debugger.
; '''GUI'''
: Graphical User Interface.
; '''GTK'''
: Toolkit for creating graphical user interfaces with support for cross platform compatibility.
; '''Hildon'''
: Application framework used in the ''Maemo platform''. Developed by Nokia and based on GNOME/GTK+ technologies, currently in the process of becoming an upstream project in gnome.org.
; '''Hildon Desktop'''
: The main user interface component of Maemo Chinook, rewrite of ''Maemo desktop''.
; '''ID'''
: Identifier.
; '''IDE'''
: Integrated Development Environment like Eclipse or QtCreator.
; '''IP'''
: Internet Protocol is a protocol used for communicating data across a packet-switched internetwork.
; '''JDK'''
: Java Development Kit.
; '''JRE'''
: Java Runtime Environment.
; '''JVM'''
: Jave Virtual Machine.
; '''ltrace'''
: Debugging utility to monitor the library calls used by a program and all the signals it receives. It can also show system calls, used by program.
; '''Maemo'''
: Software platform for mobile devices developed by Nokia, based on GNU/Linux and GNOME/GTK+ technologies. It includes proprietary components to make it work on the Nokia Maemo compatible device.
; '''maemo.org'''
: Developer community web site maintained by Nokia, main point of reference for open source and third-party developers in general.
; '''Mica'''
: Maemo IDE Common Architecture, Eclipse plugin development framework used by ESbox, PluThon and other Maemo Eclipse products.
; '''NFS'''
: Network File System is a network file system protocol allowing a user on a client computer to access files over a network in a manner similar to how local storage is accessed.
; '''OProfile'''
: System-wide profiler for Linux systems.
; '''OS'''
: Operating System or sometimes Open Source.
; '''PluThon'''
: Eclipse product implementing on-device Python development environment.
; '''Pydev'''
: Python IDE for Eclipse, which can be used in Python development.
; '''rootstrap'''
: Part of the SDK that contains selected software components from rootfs. Rootstrap is the root file system of a target inside Scratchbox.
; '''RSE'''
: Eclipse Remote System Explorer.
; '''rsync'''
: is a software application which synchronizes files and directories from one location to another while minimizing data transfer using delta encoding when appropriate.
; '''Samba'''
: is a free software re-implementation of SMB/CIFS networking protocol providing file and print services for various Microsoft Windows clients and can integrate with a Windows Server domain.
; '''SBRSH'''
: Scratchbox Remote Shell remote command execution system similar to RSH and SSH and designed for slow devices and Scratchbox's special requirements in mind.
; '''Scratchbox'''
: cross-compilation toolkit designed to make embedded Linux application development easier and to cross-compile an entire Linux distribution.
; '''SDK'''
: Software Development Kit.
; '''SSH'''
: Secure Shell network protocol that allows data to be exchanged using a secure channel between two networked devices.
; '''SSHFS'''
: SSH Filesystem or Secure SHell Filesystem is a file system client that may be used on operating systems for which an implementation of FUSE is available.
; '''TCF'''
: Eclipse Target Communication Framework.
; '''toolchain'''
: Part of the SDK that contains ARM cross compilation tools, such as compiler and linker.
; '''UI'''
: User Interface.
; '''USB'''
: Universal Serial Bus is a specification to establish communication between devices and a host controller (usually personal computers).
; '''Valgrind'''
: Tool suite for debugging and profiling Linux programs.
; '''VM'''
: Virtual Machine.
; '''VNC'''
: Virtual Network Computing is a graphical desktop sharing system that uses the RFB protocol to remotely control another computer transmiting the keyboard and mouse events from one computer to another and relaying the graphical screen updates back in the other direction, over a network.
; '''X11'''
: X Window System is a computer software system and network protocol that provides a GUI for networked computers.
; '''XML'''
: eXtensible Markup Language.

= Maemo Releases =

; '''Mistral'''
: Maemo 2.0 release for Nokia 770 device. Corresponds to the Nokia Internet Tablet SE 2006 version 2.01.2006.26-8.
; '''Scirocco'''
: Maemo 2.1 release for Nokia 770 device. Includs mainly bugfixes and some other enhancements. Corresponds to Nokia Internet Tablet SE 2006 version 2.2006.39-14.
; '''Gregale'''
: Maemo 2.2 release for Nokia 770 device (bugfixes and enhancements).
; '''Bora'''
: Maemo 3.x releases for Nokia N800 device. Corresponds to Internet Tablet OS releases "1.2006.47-20", "2.2006.51-6" (Maemo 3.0), "3.2007.10-7" (Maemo 3.1) and "4.2007.26-8"+"4.2007.38-2" (Maemo 3.2).
; '''Chinook'''
: Maemo 4.0.x releases for Nokia N800 and N810 devices. Corresponds to Internet Tablet OS releases "1.2007.44-4" (Maemo 4.0) and "2.2007.51-3" (Maemo 4.0.1)
; '''Diablo'''
: Maemo 4.1.x releases for Nokia N800, N810 and N810 WiMAX devices. Corresponds to Internet Tablet OS releases "4.2008.23-14" (Maemo 4.1), "4.2008.36-5" (Maemo 4.1.1) and "5.2008.43-7" (Maemo 4.1.2)
; '''Fremantle'''
: Maemo 5.x releases for N900 device. Corresponds to Maemo 5 OS release "1.2009.42-11" + eMMC content "1.2009.41-1" (Maemo 5) and OS release "2.2009.51-1" + eMMC content "1.2009.41-1" (Maemo 5 Update)
; '''Harmattan'''
: Maemo 6.x releases, corresponds to Maemo 6 OS release "x.2010.xx-x"

Documentation/Maemo Eclipse Tutorial/Eclipse Performance Profiling

2010-04-09T09:04:29Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Eclipse Performance Profiling =

= Introduction =

To obtain high-quality applications to be deployed on user's mobile devices, making sure that your application is bug-free is not enough. Mobile devices have limited resources, mainly CPU processing and memory. Also the way that applications interact with system resources impacts directly on performance. It is very problematic if your application crashes during execution. However, it can be worse if the application freezes due to excessive CPU processing, for example. The OProfile tool can be used to monitor your application and define bottle necks in real-world systems. In order to find problems in performance, Maemo SDK also provides OProfile packages so it can be used to profiling Maemo applications as well Internet Tablet environments.

Maemo Eclipse IDE integration products (ESbox and PluThon) provide support to profiling applications by using OProfile profiling and monitoring tool. This tutorial starts with a quickly introduction to OProfile profiling and monitoring tool. After that, it demonstrates how you can profile C/C++, Qt4 and Python applications at ESbox and PluThon using the OProfile tool integration. Finally, you can see how to interpret OProfile output at ESbox and PluThon.

= OProfile =

OProfile is an open source project that helps you to identify common performance issues, such as loop unrolling, poor cache utilization, inefficient type conversion and redundant operations, branch mispredictions, and so on. OProfile collects information about different counters: interrupt handlers, shared libraries, and much more. OProfile generates different outputs, ranging from simple tables with numbers that describe the total of samples registered during monitoring, to call graphs with detailed information about shared libraries. You can also obtain detailed source annotation, instruction-level reports and call graphs.

To start collecting profiling data, it is necessary to start opcontrol tool. It is OProfile tool that collects the information that is then used to generate profiling reports. After profiling information has been collected with opcontrol tool you can generate the reports you want to with opreport tool.

You can use OProfile on Maemo devices. However, you need to enable it on the kernel, so OProfile can monitor the system and applications. For more information about this step, see chapter [[#Configuring your Maemo device]].

= OProfile and IDE Integration =

Both Maemo Eclipse IDE integration products ESbox and PluThon provide support for OProfile tool for C/C++, Qt4 and Python projects only on Maemo device environments. It does make sense to profile Maemo applications on Scratchbox with OProfile: it would catch also host machine interruptions, signals and produce a lot of other useless information so the result would not be accurate.

OProfile support on ESbox and PluThon uses the command opreport -a -l -g to generate profiling reports. In such cases, OProfile generates the report with source file and line for each symbol (-g) and it also accumulates sample and percentage counts in the symbol list (-a). This section shows how to profile your applications at ESbox and PluThon and how to analyse profiling results.

== Configuring your Maemo device ==

If you want to configure your device to profile Maemo applications, you need to enable the Maemo device kernel to execute OProfile on it. For more information, see documentation from the OProfile site like ''OProfile Manual'' <ref name=r4>OProfile Manual. http://oprofile.sourceforge.net/doc/index.html</ref> and from maemo.org site like ''OProfiling with Maemo'' <ref name=r3>OProfiling with Maemo. http://maemo.org/development/tools/doc/diablo/oprofile/</ref>.

ESbox and PluThon products can configure the OProfile environment for you. If the system detects that your Maemo device kernel is not properly configured, a dialog prompts the user (figure [[#fig:eclipse_performance_profiling_prompt_kernel|11.1]]) to configure the kernel for OProfile.

{| summary="Profiling application with OProfile"
|+ align="BOTTOM" |'''Figure 11.1:''' Profiling application with OProfile
|-
|
[[Image:oprofile-04.png|Image oprofile-04]]
|}

== Profiling your Maemo application ==

At first, you must create a C/C++, Qt4 or Python project and select an ARMEL Scratchbox target. To run OProfile, right-click on the application (binary for C/C++ and qt4 projects or the Python script for Python projects) and select '''Profile As > Remote OProfile Profiler''', figure [[#fig:eclipse_performance_profiling_oprofile-menu|11.2]]. If the tool is not properly installed at the selected target, the system can automatically install it for you.

{| summary="OProfile Launch Menu"
|+ align="BOTTOM" |'''Figure 11.2:''' OProfile Launch Menu
|-
|
[[Image:oprofile-01.png|Image oprofile-01]]
|}

ESbox and PluThon runs your application on the Maemo device and the result is shown in the OProfile view, figure [[#fig:eclipse_performance_profiling_oprofile-view-05|11.3]]. All statistics found by OProfile are shown in an OProfile viewer, see chapter [[#Analyzing results]] for more details.

{| summary="OProfile View"
|+ align="BOTTOM" |'''Figure 11.3:''' OProfile View
|-
|
[[Image:oprofile-05.png|Image oprofile-05]]
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' If you are planning to run the OProfile profiler more than once, you will probably need to clear current OProfile view before running the current program. For that, you just need to click the '''Delete Current Sample''' button on the OProfile view toolbar. If you do not, current results are merged with the older ones.
|}

== Analyzing results ==

Each line of OProfile viewer contains the following information:

; '''Samples'''
: Shows the number of samples for each symbol.
; '''Acummulate samples'''
: Outputs accumulate sample.
; '''Percentage'''
: Shows the percentage regarding to total samples for each binary image.
; '''Acummulate percentage'''
: Shows the accumulate percentage.
; '''Line info'''
: Provides source file and line for each symbol. If the source file is not provided, the label (no location information) is shown instead.
; '''Application name'''
: Shows the name of binary image.
; '''Symbol name'''
: Shows the symbol name. If the symbol name cannot be retrived, the label (no symbols) is shown instead.

On the following figure [[#fig:eclipse_performance_profiling_oprofile-view-08|11.4]], there is an example of OProfile chapter from a Maemo C project:

{| summary="OProfile View"
|+ align="BOTTOM" |'''Figure 11.4:''' OProfile View
|-
|
[[Image:oprofile-08.png|Image oprofile-08]]
|}

In this example, we used a very simple GTK application, which only contains a simple label. On the third line (the selected line), information about library ld-2.5.so is shown in the table. For example, in about 12.030 samples (columm '''Cum. Samples'''), the library was used on 10.879 samples (4.59%). Its symbol name is known as /lib/ld-2.5.so (columm '''Symbol Name'''). This library does provides source file, so no information can be shown on '''Line Info''' columm.

== References ==
<references />

Documentation/Maemo Eclipse Tutorial/Setting Up ESbox

2010-04-09T09:04:28Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Setting Up ESbox =

= Setting up Maemo SDK Virtual Image =

The Maemo SDK, Scratchbox, and rootstraps run only on Linux/x86. If you want to use ESbox in Windows or MacOS X - or even Linux/x86-64 - then you can do this by hooking up ESbox with an appropriately configured virtual machine.

Recommended virtual machine images are provided by the [http://maemovmware.garage.maemo.org/2nd_edition Maemo SDK Virtual Image] project. That project covers the configuration and installation issues specific to the virtual machine itself. Although the project includes the term ''vmware'', the images (<nowiki>*.vmdk</nowiki> files) available there work with all the supported virtualization technology (VMware, VirtualBox and QEMU). This document covers configuring ESbox to use images to support other than native Debian-based Linux systems.

ESbox has the concept of ''Build Machines'' to distinguish the Eclipse host from the machine where C/C++ programs are built and Python programs are interpreted. For Linux/x86 hosts, the host can serve as a build machine. For other hosts, only a virtual machine can be a build machine.

ESbox uses an SSH connection with the virtual machine to perform builds, launch/debug applications, and configure Scratchbox installations and rootstraps, and a Samba connection to share project files between the machines.

An essential aspect of using ESbox with a VM is setting up ''shared folders''. In order to use all the features in Eclipse, projects and the SDK rootstrap must be visible both to the host and the VM. See chapter [[#Setting Up Shared Folders]] for an overview and setup instructions.

== Virtual Machine Engines Supported ==

ESbox supports VMware, QEMU, and VirtualBox virtualisation technologies for the Maemo SDK Virtual Image.

* VMware Workstation/Server 6.x (or Player 2.5.x and 3.x) is supported and recommended for speed. We have detected some problems using VMware Player 3.0. It seems that SSH dropouts are common in this version. VMware Player 2.5.x seems to work fine.
* VirtualBox 2.1 or newer is supported and recommended for freedom and consistency of behavior across operating systems.
* QEMU 0.9.0 and newer may be used for freedom and ease of setup, but is quite slow, even when accelerated.

== Virtual Machine Images ==

ESbox runs best with a preconfigured Ubuntu Server-based Maemo SDK Virtual Image, which has a minimal footprint. This "Server" image is configured to provide the best interaction with ESbox. The "Server" image may be used with any of the virtualisation engines above.

The ESbox wizard '''File > New > Other > Maemo Installers > Maemo SDK Virtual Image''' lets you fetch and install the recommended images maintained by the [http://maemovmware.garage.maemo.org/ Maemo SDK Virtual Image] project in concert with the Maemo Eclipse Integration project. The "Server" image comes "bare", without any pre-installed Maemo SDK. ESbox supports installing Maemo SDK and development environments for C/C++, Python and Qt4 from the installer wizard.

As an lternative to the "Server" image, you can try a Ubuntu Desktop-based Maemo SDK Virtual Image if you want a full out-of-the-box ready environment pre-installed. This "Desktop" image contains fully-configured ESbox and Maemo Diablo and Fremantle SDK development environments inside.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' You should not use the "Desktop" image with native ESbox installation (configuration where Eclipse IDE has been installed to the host PC instead of Maemo SDK Virtual Image) as the "Desktop" image already includes ESbox pre-installed.
|}

If you want to use your own virtual image instead of Maemo SDK Virtual Images, ensure it has SSH and Samba support. For SSH, the UseDNS flag should be switched off, and to support Samba, you may need an often-running cron job to resynchronize the clock with the host, to avoid timestamp drift issues when building, see the chapter [[#Clock synchronization]].

=== Networking Setup ===

A very important aspect of the ESbox and VM configuration is the ''networking mode''. Modern VM engines usually allow three modes for how the VM virtualizes network access: ''host'', ''NAT'', and ''bridged''.

''Host'' is useless for ESbox, since it implies that the outside world cannot see the VM, and ESbox would be on the outside. Don't use this mode.

''NAT'' is a mode where the VM shares the IP address of the host. This is useful in a lot of cases with ESbox, but it is not appropriate in the default configuration recommended by ESbox, where the address 127.0.0.1:2222 is used to talk to the VM.

* Shared folders cannot be exposed from the VM to the host, which makes it difficult to use C/C++ indexing and searches with the Maemo SDK. This is because we cannot use port forwarding to remap the Windows CIFS ports to distinguish the hosts from the VMs.
* SBRSH does not work, since the device communicates with sbrsh running under Scratchbox, but the IP address is the same as the host, which does not run the server. Complex port forwarding could make this work too, but it is not worth the effort.

VMware does provide a vmnet8 interface for NAT which has a unique IP address. Unfortunately, this doesn not work reliably.

If you are able to get this working, then you ''can'' use NAT with shared folders and SBRSH.

Since it is not an easy setup, we don not recommend using this mode, unless you know what you are doing, or you have no other choice (for example, QEMU).

''Bridged'' is a mode where the virtual machine has its own IP address on the LAN. To all intents and purposes it appears to be a distinct machine on the network. This gives it enough flexibility to support the shared folder mappings and SBRSH usage mentioned above.

On the other hand, Bridged mode introduces the inconvenience that the DHCP-assigned address of the VM may change between restarts of the machine. This means you need to manually correct the address (for example, in the '''Machine Access''' pane described below). But ESbox provides helpful dialogs reminding you that you may need to update this address and I myself have used it successfully for months.

So, ''Bridged'' mode is the best of the three options and we recommend this one. This is the default for the "server image" provided by the maemovmware project. If you want to change to NAT, you need to reconfigure the networking devices for the given image in the VM engine of choice. See your documentation for details.

== ESbox Build Machine Configuration ==

Configuration is under '''Window > Preferences > ESbox > Build Machines'''. If you navigate here before configuring anything, or try to create a project and launch first, you will get a message directing you to the page, figure [[#fig:virtual_machine_dialog_select_build_machine|6.1]].

{| summary="Build machine selection reminder"
|+ align="BOTTOM" |'''Figure 6.1:''' Build machine selection reminder
|-
|
[[Image:dialog-select-build-machine.png|Image dialog-select-build-machine]]
|}

You need to select a virtual machine engine (or '''Manual configuration''') and adjust the settings on all the pages accordingly. Each engine has product-specific configuration.

Any selected build machine has a unique configuration in ''Machine Access'' (the user name, password, target/host addresses and ports) and ''Shared Folders'' (the shares providing a mapping between the host and target filesystems) tabs. All machines except for ''Manually Launched'' have a VM-specific configuration tab as well.

== Virtual Machine Specific Configuration ==

=== VMware Configuration ===

The '''Product type''' field lets you select along multiple available VMware engines if you have more than one installed. This is mostly useful if you have installed VMware Workstation or Server, but want to use VMware Player (since they exist in the same directory).

{| summary="VMware Options"
|+ align="BOTTOM" |'''Figure 6.2:''' VMware Options
|-
|
[[Image:prefs-esbox-build-machines-vmware.png|Image prefs-esbox-build-machines-vmware]]
|}

The '''Installation directory''' field should point to either the directory containing vmrun, vmware or vmplayer (in any host) or the VMware Fusion[.app] application or library support directory (in Mac OS X).

ESbox prefers to use vmrun[.exe] for all operations as a command-line controller for virtual machine operations (enumerating, launching, and stopping virtual machines). ESbox is flexible and will look up the directory tree from the specified location to locate the expected executable. If you only have VMware Player, or only want to use player, point to the directory where vmplayer[.exe] exists and set the Product Type to '''Player'''.

The VMX path is the primary file describing the virtual machine (which disk images it uses, what its networking configuration is, and so on). You can edit its settings in a running VMware client.

=== VirtualBox Configuration ===

The '''Executable''' should be the VBoxManage program, which is the command line controller for VirtualBox. ESbox uses this to detect whether machines are running, which machines are available (under the '''Virtual Machine''' dropdown), and to launch and stop machines.

{| summary="VirtualBox Options"
|+ align="BOTTOM" |'''Figure 6.3:''' VirtualBox Options
|-
|
[[Image:prefs-esbox-build-machines-virtualbox.png|Image prefs-esbox-build-machines-virtualbox]]
|}

The '''Command''' pattern spells out how VBoxManage is launched (where $VIRTUALBOX is the "executable" path). This probably needs no changes.

The '''Virtual Machine''' dropdown allows you to select one of the registered VirtualBox machine instances. In VirtualBox, all machine instances must be registered. See the [http://maemovmware.garage.maemo.org/2nd_edition/create_vbox_machine.html Maemo SDK Virtual Image] documentation for details.

=== QEMU Configuration ===

The '''Installation Directory''' should point to the top-level directory where the QEMU data files (<nowiki>*.bin</nowiki>) are located. This may differ from the executable's path.

{| summary="QEMU Options"
|+ align="BOTTOM" |'''Figure 6.4:''' QEMU Options
|-
|
[[Image:prefs-esbox-build-machines-qemu.png|Image prefs-esbox-build-machines-qemu]]
|}

The '''Executable''' is the filename (inside the installation directory) or a full path to the qemu executable.

The '''Command pattern''' is the template used to launch QEMU. Most likely the only edits you would apply would be to remove some of the options (like -kernel-kqemu, -usb, etc.) or to add additional redirections. See the [http://www.nongnu.org/qemu/user-doc.html QEMU documentation] for a description of these options.

The '''Memory size (Mb)''' tells how much RAM to allot to the virtual machine. This should usually be at least 512 Mb for C/C++ compilation.

The '''Disk image(s)''' field is a comma-separated list of full paths to disk images. These images are assigned, in order, to /dev/hda, /dev/hdb, and so on. QEMU supports multiple kinds of disk images (see docs for details). You can use the same maemovmware project VMware <nowiki>*.vmdk</nowiki> images here.

=== Machine Access ===

Some fields in the '''Machine Access''' settings should be preconfigured to match the images from the Maemo SDK Virtual Image project, but you need to edit the address and port settings depending on your networking configuration, figure [[#fig:virtual_machine_prefs_esbox_build_machines_machine_access|6.5]].

{| summary="Machine access"
|+ align="BOTTOM" |'''Figure 6.5:''' Machine access
|-
|
[[Image:prefs-esbox-build-machines-machine-access.png|Image prefs-esbox-build-machines-machine-access]]
|}

Use the '''Autoselect Network Settings''' button to try to guess the networking settings from current virtual machine settings and the host machine's network interfaces. This assumes the virtual machine engine, image, and configuration have all been specified correctly. In any case, this is a guess, so read the diagnostic messages, figure [[#fig:virtual_machine_prefs_esbox_build_machines_autoselect_nat|6.6]].

{| summary="Autoselect NAT"
|+ align="BOTTOM" |'''Figure 6.6:''' Autoselect NAT
|-
|
[[Image:prefs-esbox-build-machines-autoselect-nat.png|Image prefs-esbox-build-machines-autoselect-nat]]
|}

Note, when configuring a virtual machine using Bridged networking, it is impossible to guess the actual address the machine will have. By default, ESbox selects the ''network address'' (<nowiki>*.0</nowiki>) and warns you to update it, figure [[#fig:virtual_machine_autoselect_bridged|6.7]].

{| summary="Autoselect bridged"
|+ align="BOTTOM" |'''Figure 6.7:''' Autoselect bridged
|-
|
[[Image:prefs-esbox-build-machines-autoselect-bridged.png|Image prefs-esbox-build-machines-autoselect-bridged]]
|}

Use the '''Validate''' button to launch the machine or find a running instance and run through a series of tests to validate that the machine is configured properly. If Scratchbox is not yet installed on the target machine, then validation does not pass all the tests.

After closing the dialog, use the '''Apply''' button to accept the changes and launch the virtual machine, if needed.

If you have previously configured a Build Machine and have changed the settings, ESbox may present this dialog, figure [[#fig:virtual_machine_shut_down_vm|6.8]].

{| summary="Shut down?"
|+ align="BOTTOM" |'''Figure 6.8:''' Shut down?
|-
|
[[Image:esbox-shut-down-vm.png|Image esbox-shut-down-vm]]
|}

If the machine and disk are the same as the running machine, and you are just synchronizing network settings, you may be able to leave it running. In any event, the supported VM engines themselves are not able to write to the same disk images opened by another engine.

=== More Details ===

The Machine Access tab allows you to configure the networking and authentication with the VM. '''User''' is the account which acts as the agent for all operations with the VM. It should be the same user who owns the Scratchbox installation(s). '''Password''' is the password for the user account.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' For Maemo SDK Virtual Images, the default user is "maemo" and the password is "maemo".
|}

'''Target address''' is the address used to access the VM. This may be an IP address or a name. If the '''Autoselect Settings''' button cannot figure it out, you need to discover this experimentally, by watching the boot-time messages, or logging in and using /sbin/ifconfig to see what address is assigned to eth0.

'''Target SSH port''' is the SSH port. This defaults to 2222 for NAT configurations. The default for normal SSH usage is 22, but if the Target address is 127.0.0.1, this port must be remapped to avoid conflicts with the host.

For VirtualBox, this port must match the configuration established for a machine via VBoxManage before the machine is launched. See more instructions from the [http://maemovmware.garage.maemo.org/2nd_edition/vbox_installers.html Maemo SDK Virtual Image VirtualBox configuration] document, the [http://maemovmware.garage.maemo.org/2nd_edition/create_vbox_machine.html Maemo SDK Virtual Image port forwarding] document, or the Network Address Translation chapter of the VirtualBox manual.

For VMware, the port must be configured using the '''Virtual Network Editor > NAT > Edit > PortForwarding...''' dialog. Redirect SSH by adding a '''Incoming TCP port''' entry with '''Host Port''' 22, '''Virtual Machine Address''' matching the Target Address, and a '''Port''' like 2222 or 2244 matching the Target SSH Port setting.

In Windows VMware, if the VMnet1 and VMnet8 devices are not enabled or do not work as expected, be sure they are associated with TCP/IP services. In some situations, these can remain unconfigured. Go to '''Control Panel > Network Connections''' and bring up '''Properties''' for '''VMware Virtual Ethernet Adapter for ...'''. In the '''General''' tab, under '''This connection uses the following items:''', enable '''Internet Protocol (TCP/IP)'''

If you use both VirtualBox and VMware, be sure to use different SSH ports when enabling port forwarding; otherwise they conflict.

For QEMU, this option dictates which port is used, since it is controlled when the machine is launched.

'''Host address''' is the name of the host as seen from the VM - this is never 127.0.0.1<nowiki>! The value depends on the kind of networking you are using with the VM. </nowiki>

For VMware, see the '''VM > Removable Devices > Network Adapter''' menu.

For VirtualBox, see the '''machine > Settings > Network > Adapter''' dialog. If necessary, you can find this by logging into the VM (maemo/maemo) and invoking /sbin/ifconfig.

For QEMU, the default is 10.0.2.2 since the IP is shared with the VM and a private subnet is used to reference the host.

== Shared Folders ==

On the '''Shared Folders''' tab, specify the shared folders that ESbox uses to map filesystem paths between the host and VM filesystem. Here you specify mappings for the existing and configured shared folders in the host and VM. You must manually configure file sharing yourself.

See [http://esbox.garage.maemo.org/2nd_edition/shared_folders.html ESbox Shared Folders] document for an overview and setup instructions.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Currently ESbox only supports Samba (Windows/CIFS) shared folders.
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' To expose shares from the VM to the host, you must use Bridged networking in the VM. Otherwise you need to understand a lot about port forwarding.
|}

=== Configuration ===

The default shares are suggestions for the most common setup, so that projects can be built for multiple Scratchbox targets, and so indexing can work. See [http://esbox.garage.maemo.org/2nd_edition/shared_folders.html ESbox Shared Folders] document for details.

{| summary="Shared folders"
|+ align="BOTTOM" |'''Figure 6.9:''' Shared folders
|-
|
[[Image:prefs-esbox-build-machines-shared-folders.png|Image prefs-esbox-build-machines-shared-folders]]
|}

If '''Local share?''' is yes, you need to configure file sharing on your host and expose a share which can be mounted by the VM. This typically is yes for normal usage (since the Eclipse workspace must be on the local machine). If the setting is no, then in the Maemo SDK VM images, expose the mount in /etc/samba/smb.conf.

'''Add Host Share...''' lets you add an entry from the shared folders exposed on the host. These must be manually configured.

'''Add VM Share...''' lets you add an entry from the shared folders exposed from the virtual machine. This requires that the VM be launched and validated before the button is enabled.

ESbox can automatically mount folders from the host to the virtual machine and from the virtual machine to the host. This dialog appears when ESbox wants to mount a share:

{| summary="SMB Mount"
|+ align="BOTTOM" |'''Figure 6.10:''' SMB Mount
|-
|
[[Image:esbox-mount-share.png|Image esbox-mount-share]]
|}

The '''username''' is, by default, the same as the main user account on the given machine, but you may change it if needed, depending on the share's permissions.

The '''workgroup/domain''' may not be required unless you are logged into a Windows domain.

The '''password''' is remembered for future launches of the mount during the current Eclipse session, but it is discarded if the mount fails.

To prevent ESbox from trying to mount the share, change the '''Auto mount?''' setting to '''No'''.

=== Dynamic shared folder status ===

The '''Check folder status while editing''' checkbox dynamically validates the shared folders against a running VM, to assist with some issues that may be tedious to debug by using '''Validate Machines'''.

To use this:

# Be sure the '''Machine Access > Target Address''' and '''Host Address''' fields are valid.
# Be sure the VM has been launched (using '''Launch Machine''' or a previous '''Validate Machine''' invocation).
# Enable the checkbox.
# Edit the entries in the table. The status is updated as you change the fields.

{| summary="Shared folders"
|+ align="BOTTOM" |'''Figure 6.11:''' Shared folders
|-
|
[[Image:prefs-esbox-build-machines-shared-folders-2.png|Image prefs-esbox-build-machines-shared-folders-2]]
|}

== ESbox Virtual Machine Behavior ==

=== Launching ===

Usually, only an explicit user action (like starting a wizard, validating the VM, or viewing ESbox or Maemo preference panels) requires the VM to be running. ESbox connects to a running virtual machine that responds to the configured machine engine, target address, and SSH port in the Machine Access settings. If the specified engine or configured image is not running, then ESbox prompts you to launch the configured machine, figure [[#fig:virtual_machine_launch_vm|6.12]].

{| summary="Virtual Machine Needed"
|+ align="BOTTOM" |'''Figure 6.12:''' Virtual Machine Needed
|-
|
[[Image:esbox-launch-vm.png|Image esbox-launch-vm]]
|}

If the virtual machine is running, but the target cannot be contacted (that is, the SSH address is incorrect), it presents this variant, which indicates the network settings are probably incorrect, figure [[#fig:virtual_machine_launch_vm_bad_network|6.13]].

{| summary="Virtual Machine Needed, network problem"
|+ align="BOTTOM" |'''Figure 6.13:''' Virtual Machine Needed, network problem
|-
|
[[Image:esbox-launch-vm-bad-network.png|Image esbox-launch-vm-bad-network]]
|}

# Check the '''Build Machines''' preferences to validate that the '''Machine Access''' settings match.
# Check '''Network Connections''' preferences in case you are behind a proxy but the VM is not. ESbox uses the proxy settings for all network operations.
# Check the [http://maemovmware.garage.maemo.org/ Maemo SDK Virtual Image] documentation in case you need to finish configuring your VM. This can be a laborious process if you are using NAT networking, as documented elsewhere in this document.

Both dialogs allow you to launch the virtual machine anew or take one of the actions under '''Help''' (which cancels the current operation) and let you look for other solutions.

Choose '''Launch now''' when you know the machine is not running, and you want ESbox to start it.

Choose '''It's running''' if the machine is running and there was a configuration problem that was fixed in the meantime - for example, ESbox was trying to contact the VM before the SSH server was started, or you have just corrected the virtual machine's settings (you ran dhclient or switched between NAT and Bridged modes so that the given address works), or you have fixed the Network Proxy settings in the meantime.

If ESbox still cannot detect the machine, it reports a failure. If you think the VM is running but ESbox tells you it "has stopped running", be sure you are using exactly the same machine (watch out for multiple copies on your disk, since the full path to the <nowiki>*.vmx</nowiki> file matters).

Choose '''Cancel''', of course, if you do not want to start the virtual machine. This cancels any operation that requested it.

While the VM is launching, this dialog is shown, figure [[#fig:virtual_machine_launching_vm|6.14]].

{| summary="Launching Virtual Machine"
|+ align="BOTTOM" |'''Figure 6.14:''' Launching Virtual Machine
|-
|
[[Image:esbox-launching-vm.png|Image esbox-launching-vm]]
|}

The dialog remains for a few seconds after boot time. You can expand it in case the machine has booted but the dialog remains, figure [[#fig:virtual_machine_launching_vm_expanded|6.15]].

{| summary="Launching Virtual Machine, expanded"
|+ align="BOTTOM" |'''Figure 6.15:''' Launching Virtual Machine, expanded
|-
|
[[Image:esbox-launching-vm-expanded.png|Image esbox-launching-vm-expanded]]
|}

Closing this dialog does not cancel any operation. It is only informative, to help you look for common problems and solutions while configuring the machine.

=== Shared folder mappings ===

Once you have configured mapping that expose the project to the VM, ESbox automatically selects a project location inside a shared folder for you, when you create or import a project, figure [[#fig:virtual_machine_new_project_vm|6.16]].

{| summary="Default project location"
|+ align="BOTTOM" |'''Figure 6.16:''' Default project location
|-
|
[[Image:esbox-new-project-vm.png|Image esbox-new-project-vm]]
|}

In fact, if the dialog presents an error about the project location not being visible, this means your shared folder mappings are insufficient, because no valid mapping satisfies the goal. This mapping depends on the mapping constraints for the union of the selected targets, figure [[#fig:virtual_machine_new_project_vm_bad|6.17]].

{| summary="Project location, not visible"
|+ align="BOTTOM" |'''Figure 6.17:''' Project location, not visible
|-
|
[[Image:esbox-new-project-vm-bad.png|Image esbox-new-project-vm-bad]]
|}

Once you have established mappings exposing the Maemo SDK to the host, ESbox uses these mappings to populate the C/C++ indexer settings when you create, import, or convert a project, figure [[#fig:virtual_machine_indexer_settings|6.18]].

{| summary="Indexer settings"
|+ align="BOTTOM" |'''Figure 6.18:''' Indexer settings
|-
|
[[Image:esbox-project-indexer-settings.png|Image esbox-project-indexer-settings]]
|}

(If you need to change your shared folder setup, or change other things that invalidate these settings, you can use '''Project > Index > Reset Paths and Symbols or Project > Index > Add Missing Paths and Symbols''' to regenerate them from the current mappings.)

== Clock synchronization ==

When you perform C/C++ builds in ESbox, it is essential that the clock settings in the host and the virtual machine match, since they share a Samba filesystem whose timestamps determine whether any work needs to be done. If they mismatch, then either your Make output is littered with "timestamp drift" messages or your programs are not rebuilt as expected.

Unfortunately, the virtual machine engine and configuration influence the clock in different ways. (For example, in VMware, the clock may act differently depending on whether the VMware Tools are installed.) You will need to manually configure your system and experiment to make things work.

One approach is:

# Log into the virtual machine.
# Disable the /etc/cron.minutely/00resetclock script (that is, comment out the hwclock command). This currently runs without appropriate options in respect to the timezone. But note that the clock can drift (without VM engine tools support).
# Reconfigure the time zone to match the one you use in the host, using sudo dpkg-reconfigure tzdata.
# Edit /etc/default/rcS and set UTC=no.
# Edit /etc/profile and comment out the line: export TZ=Europe/London.
# Reboot.
# Sync the clock. Run sudo /sbin/hwclock -localtime -hctosys.
# Verify the time, using date. This should match the current time on the host.

Now, you can create files in a shared folder and validate their timestamps to match those on the host. In my experiments with VMware Fusion on OS X, unfortunately, the timstamps were off by as much as 5 seconds. So this led to several annoying messages if I built several times in a row, but it is manageable.

== PC Connectivity Interaction ==

Here are some tips and tricks for using [http://pc-connectivity.garage.maemo.org/ PC Connectivity] with ESbox and virtual machines.

=== Using USB, Bluetooth, WLAN ad-hoc Networking (static IPs) ===

USB, WLAN Ad-Hoc, and Bluetooth connections use static addresses (192.168.*.15). The default network routing configurations for the host mean that they are only able to directly communicate back and forth with one "machine" at a time. In most cases, you should connect the machine to the host, rather than the virtual machine. Eclipse manages most of the SSH traffic with the device, so the host needs to be able to see the device at its static address. The host cannot see network traffic inside the VM.

Conversely, from the device point of view, the device can only see the machine it is connected to. For cases where the device needs to open a socket from the host, the device must be able to see the host at the host address (192.168.*.14). This includes Python debugging and SBRSH.

Note: if you are using NAT networking with the virtual machine, the VM is also able to see the device at the static address. This is the best of both worlds.

Note: When using SBRSH, you most likely need to use WLAN instead of a static IP configuration. The device must be visible on the network inside the virtual machine and the host machine, since SBRSH runs under Scratchbox, and the device needs to mount filesystems from the VM and host.

=== Using WLAN Networking ===

WLAN networking is the most flexible option, as long as your virtual machine is configured for Bridged networking, where it has its own DHCP-acquired address. In this model, the host, the VM, and the device are all peers on the LAN. Thus, the device is visible to the host and the VM, and the device can see the host and the VM.

Unfortunately, of course, WLAN is very slow and prone to packet loss. It can be more difficult to use when debugging, for example.

== Troubleshooting ==

'''Cannot access the machine'''

* If ESbox cannot guess your network properly, look at the boot screen for the VM or login to the VM (maemo/maemo) and run sudo dhclient to validate the assigned IP address for the VM, if you are not getting a connection. Only in the case of NAT should you enter 127.0.0.1 as the Target address in ESbox. For non-NAT cases, the host address is usually xx.xx.xx.2 of the target address.
* ping is a very useful feature. In case of connection problems, cross-check the address displayed, for example, in a launch configuration or in the RSE connection, and verify that you can see if they are from your host or your VM (depending on context).
* If you are having trouble accessing port forwarding over SSH, note that VMware's virtual network port mappings apply even when it is not hosting a running VM. In such cases, select different target ports for other VM engines.

'''Scratchbox not found'''

* If you have first set up a machine and have had some difficulties with configuring it, you can set ESbox up to make it detect Scratchbox and targets. Go to '''Window > Preferences > Maemo > Installed Targets''' and hit '''Refresh'''.

'''Shared folder issues'''

* See [http://esbox.garage.maemo.org/2nd_edition/shared_folders.html ESbox Shared Folders] document, troubleshooting chapter for more information.

'''Device access issues'''

* The device must be connected to the host (not the VM) in most cases, except for SBRSH (which must use WLAN in most cases).
* Watch out for firewall software thwarting you. It may block all access to your device. Allow traffic to the 192.168.* IP range.
* If your LAN uses 192.168.{2,3,4}.* for its own DHCP server, and you want to use the static USB, Bluetooth, or WLAN ad-hoc connections, you need to have separate subnets. Reconfigure these static addresses in the PC-Connectivity Manager and in your host configuration.
* Avoid host-only networking configurations in your VM. Otherwise you are unable to contact the device or the Internet.
* SBRSH needs to communicate in three ways: between the host (running Eclipse), the VM (hosting Scratchbox and running the sbrsh client), and the device (running the sbrsh daemon). In most cases, you must use WLAN for this to work, unless you know how to manually configure routing tables to do this over USB or Bluetooth or the ad-hoc WLAN connection.

'''Virtual machine launching when not using ESbox'''

* Eclipse sometimes triggers builds for all projects in the workspace, which may be a problem if you are using other products in your installation and do not want to be prompted to launch the VM.
* The easiest solution is to switch the '''Build Machine''' to '''None'''. (With this setting, you cannot use most ESbox actions, since no installed targets except for Remote Connections are recognized.) An alternative is to use the '''Manually Launched Machine''' setting. If you use ESbox commands, it fails to connect immediately if no machine responds to the address.
* Alternately, a configured build machine can live alongside other products if you avoid allowing Eclipse to build ESbox projects: Close ESbox projects or Disable '''Project > Build Automatically''' and Disable '''Window > Preferences > Run/Debug > Build (if required) Before Launching'''

= Setting Up Shared Folders =

== Overview ==

Shared folders are needed when you run ESbox with a virtual machine outside the Debian Linux/x86 host. See [http://esbox.garage.maemo.org/2nd_edition/virtual_machines.html ESbox Using Virtual Machines] and chapter [[#Setting up Maemo SDK Virtual Image]] for the primary documentation on virtual machines.

In this configuration, the Maemo SDK (build tools, rootstrap, and so on) is contained inside the filesystem of a virtual machine, and is not directly accessible to the host. Conversely, the projects that you create and edit in Eclipse are created in the host filesystem, and are not directly accessible to the VM.

In order for most ESbox features to work, you must set up and configure shared folders to connect these filesystems together.

* Set up: you must manually set up file sharing in your host and in your VM if you are using a custom image not provided by the [http://maemovmware.garage.maemo.org/ Maemo SDK Virtual Image] project.
* Configure: you must tell ESbox what shares you have configured on the '''ESbox > Build Machines preference''' page like described in [http://esbox.garage.maemo.org/2nd_edition/virtual_machines.html ESbox Using Virtual Imges] documents and chapter [[#Shared Folders]].

See a diagram explaining how this works in an example Windows configuration, figure [[#fig:virtual_machine_exbox_shared_folder_mapping|6.19]].

{| summary="ESbox shared folder mapping"
|+ align="BOTTOM" |'''Figure 6.19:''' ESbox shared folder mapping
|-
|
[[Image:esbox-shared-folder-mapping.png|Image esbox-shared-folder-mapping]]
|}

=== Sharing Eclipse Projects ===

In Eclipse, projects are traditionally created in the host filesystem. Projects are created in the host filesystem by convention. CDT has some support for creating projects on a network using EFS, but EFS-based projects are not properly supported by all the 3rd party plugins that ESbox uses.

The Maemo SDK needs to be able to "see" the project location in order to build your project, so the project location should be inside a directory, which is shared to the virtual machine. For example, in Windows, you may have a shared folder c:/textbackslash/maemo/shared. You create projects somewhere inside this tree. The share has read-write permissions so the build can generate object files and executables. The Eclipse workspace itself does not have to live inside the shared folder, but it can be simpler to understand.

At the same time, the shared folder from the host must be mounted in the VM in a location visible to the rootstrap, so that the SDK build tools can locate your C/C++ sources and headers or Python scripts.

Scratchbox 1 uses a sandbox model, whch means only files inside certain directories of /scratchbox are visible. It is best to select a directory that does not change locations for different rootstraps, such as the user's home directory inside SB1. A suitable location is /scratchbox/users/<user>/home/<user>/shared.

For Scratchbox 2, a similar kind of sandboxing occurs, but it is slightly less restrictive. We recommend mounting any shares inside the user's home directory. A suitable location is /home/<user>/shared.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' This choice exposes occasional problems when Unix filesystem semantics are not fully emulated over Samba shares, such as when softlinks are created by build scripts, and building is a little slower than with a native filesystem. But we chose to optimize for ease of Eclipse integration and speed of IDE/editor/debugger-time activity over build-time performance.
|}

=== Sharing Maemo SDK ===

CDT's C/C++ indexer parses the sources and headers of C/C++ projects, so you can look up <nowiki>#includes</nowiki> and use code completion, symbol lookup, cross-referencing, type/call hierarchies, and so on. The indexer data is also used to resolve symbols for use by Maemo C++ hover help.

For this parsing to be complete and cover most of the identifiers defined or referenced in your project, the Maemo SDK headers need to be visible to the indexer. The easiest way to do this with the stock C/C++ Includes and Symbols UI is to have the Maemo SDK visible to the host filesystem. CDT supports offline or precompiled indexes, which would obviate the need to directly expose the SDK to the host. This feature was not implemented in ESbox but, it is worthwhile to expose the SDK contents to the host so you can browse Maemo headers in the editor.

This kind of sharing is not required for normal build, launch, or debug operations.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' For sharing from the VM to the host, the network adapter setup in the VM should be Bridged Networking.
|}

NAT networking requires port forwarding over the CIFS port 445 to avoid conflicting with the SMB/CIFS server in host PC, but Windows at least does not easily allow you to specify an alternate CIFS port with programs like NET USE. Also, in Mac OS X, VMware Fusion does not appear to support user-configured port forwarding.

The virtual machine must export shares so the Maemo rootstraps can be mounted in the host. You want to capture the compilers and users/.../targets directories for Scratchbox 1 (/scratchbox captures both) and the /home/.../.maemo-sdk directory for Scratchbox 2 (the /home/<user> directory is good enough).

The [http://maemovmware.garage.maemo.org/ Maemo SDK Virtual Images] will export these shares by default.

== Default Shared Folders Configuration ==

ESbox publishes default shares when you configure a new build machine. For Eclipse project sharing, ESbox provides these shares:

* Local share = Yes
* Share path = c:/maemo/shared or /home/<user>/Public
* Mount path = /scratchbox/users/maemo/home/maemo/shared

and

* Local share = Yes
* Share path = c:/ maemo/shared or /home/<user>/Public
* Mount path = /home/maemo/shared

Feel free to change the Share Path to whatever you have on your system. The Mount Paths, though, have been selected specially. They point into the user's home on the VM so that Scratchbox 1 and Scratchbox 2 can see the projects in the same Scratchbox-relative directory at build time. Additionally, they point to a location that map the same no matter which target you are building.

For Maemo SDK sharing, ESbox provides these shares:

* Local share? = No
* Share path = /scratchbox
* Mount path = S: or /Volumes/scratchbox

and

* Local share? = No
* Share path = /home/maemo
* Mount path = T: or /Volumes/maemo

Again, change the Mount Path according to your preferences.

These shares allow access to enough of the SDK to allow full C/C++ indexing. The home directory is exposed mainly because Scratchbox 2 places SDKs under ~/.maemo-sdk. However, we suggest the whole home directory, which may be useful, if you want to move files back and forth between the host and VM.

== How to Make Shares in Windows XP ==

Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).

=== Enabling sharing services ===

Be sure to enable '''Windows File & Print Sharing'''. You will see it on a fresh system when you first select '''Sharing & Security...''' from a folder's context menu in Windows Explorer. Alternately, visit '''Control Panel > Administrative Tools > Services''' and enable the '''Server''' service.

=== Exporting shares ===

Under Windows Explorer, right click on a folder and select '''Sharing and Security...''', figure [[#fig:shared_folders_xp_share_menu|6.20]].

{| summary="Sharing and Security..."
|+ align="BOTTOM" |'''Figure 6.20:''' Sharing and Security...
|-
|
[[Image:xp-share-menu.png|Image xp-share-menu]]
|}

You will see a dialog for configuring a share, figure [[#fig:shared_folders_xp_share_dialog|6.21]].

{| summary="shared Properties"
|+ align="BOTTOM" |'''Figure 6.21:''' shared Properties
|-
|
[[Image:xp-share-dialog.png|Image xp-share-dialog]]
|}

Check '''Share this folder'''.

Edit the '''Share name''', if needed. You need to enter the same value in the Shared Folders page. Usually this is the same as the last segment of the shared folder.

For '''User limit''', you may choose to limit the number of users. ESbox will attempt to share a folder into a VM only once, even if you have multiple mappings established, by using bind mounts to mirror the original mount.

Edit the '''Permissions''' and ensure that your local user account (who runs Eclipse) has '''Full Control''' (change and read). The build process needs to write object files, dependencies, and executables, figure [[#fig:shared_folders_xp_share_permissions|6.22]].

{| summary="Share Permissions"
|+ align="BOTTOM" |'''Figure 6.22:''' Share Permissions
|-
|
[[Image:xp-share-permissions.png|Image xp-share-permissions]]
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox does not propose adding mappings for exported drives.
|}

== How to Make Shares in Windows Vista ==

Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).

=== Enable file sharing services ===

Under '''Control Panel > Network and Internet > Network and Sharing Center''', the entry '''Sharing and Discovery > File sharing''' should be '''On''', figure [[#fig:shared_folders_vista_share_config|6.23]].

{| summary="Sharing and Discovery"
|+ align="BOTTOM" |'''Figure 6.23:''' Sharing and Discovery
|-
|
[[Image:vista-share-config.png|Image vista-share-config]]
|}

=== Exporting shares ===

Under Windows Explorer, right click on a folder and select '''Share...''', figure [[#fig:shared_folders_vista_menu_share|6.24]].

{| summary="Share..."
|+ align="BOTTOM" |'''Figure 6.24:''' Share...
|-
|
[[Image:vista-menu-share.png|Image vista-menu-share]]
|}

Ensure that your local user account (who runs Eclipse) is in the share list, and has '''Permission Level''' = '''Owner''' (read and write). The build process needs to write and delete object files, dependencies, and executables, figure [[#fig:shared_folders_vista_share_permissions|6.25]].

{| summary="Share permissions"
|+ align="BOTTOM" |'''Figure 6.25:''' Share permissions
|-
|
[[Image:vista-share-permissions.png|Image vista-share-permissions]]
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox does not propose adding mappings for exported drives.
|}

== How to Make Shares in Windows 7 ==

Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).

=== Enable sharing ===

Under '''Control Panel > Network and Internet > Choose homegroup and sharing options > Change advanced sharing settings...''', the entry '''Turn on file and printer sharing''' should be selected, figure [[#fig:shared_folders_w7_sharing_options|6.26]].

{| summary="File and printer sharing"
|+ align="BOTTOM" |'''Figure 6.26:''' File and printer sharing
|-
|
[[Image:w7-sharing-options.png|Image w7-sharing-options]]
|}

=== Exporting shares ===

Under Windows Explorer, right click on a folder and select '''Properties''', figure [[#fig:shared_folders_w7_sharing_menu|6.27]].

{| summary="Properties"
|+ align="BOTTOM" |'''Figure 6.27:''' Properties
|-
|
[[Image:w7-sharing-menu.png|Image w7-sharing-menu]]
|}

Select '''Share''', figure [[#fig:shared_folders_w7_sharing_folder_properties|6.28]].

{| summary="Share..."
|+ align="BOTTOM" |'''Figure 6.28:''' Share...
|-
|
[[Image:w7-sharing-folder-properties.png|Image w7-sharing-folder-properties]]
|}

Ensure that your local user account (who runs Eclipse) is in the share list, and has '''Permission Level''' = '''Owner''' (read and write). The build process needs to write and delete object files, dependencies, and executables.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox does not propose adding mappings for exported drives.
|}

== How to Make Shares in Mac OS X ==

=== Enabling Windows/SMB File Sharing ===

Open '''System Preferences > Sharing'''. Click the lock and enter an administrator's credentials to make changes.

Enable '''File Sharing'''. Click '''Options....'''

Check the option '''Share files and folders using SMB'''. This is the protocol used for Windows-style file sharing, figure [[#fig:shared_folders_osx_share_smb_enable|6.29]].

{| summary="Enable SMB sharing"
|+ align="BOTTOM" |'''Figure 6.29:''' Enable SMB sharing
|-
|
[[Image:osx-share-smb-enable.png|Image osx-share-smb-enable]]
|}

Click '''Options....'''

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' In Snow Leopard (10.6 or newer), you have to enable encrypted password support in Samba in the virtual machine. Inside the VM, edit /etc/samba/smb.conf and change the line under the "Authentication" section: encrypt passwords = false to encrypt passwords = true
|}

If this is not done, you encounter numerous failed password attempts. Other host operating systems and Samba/SMB/CIFS versions may not allow usage of unencrypted passwords.

=== Exporting Shares ===

Use the default shares for your account (''Public'', which is under /home/<user>/Public), or create new ones. Ensure your user account (who runs Eclipse) has '''Read and Write''' permissions, figure [[#fig:shared_folders_osx_share_prefs|6.30]].

{| summary="File Sharing"
|+ align="BOTTOM" |'''Figure 6.30:''' File Sharing
|-
|
[[Image:osx-share-prefs.png|Image osx-share-prefs]]
|}

The '''Share name''' used in ESbox comes from the label under '''Shared Folders'''.

== How to Make Shares in Linux ==

=== Enabling File Sharing ===

This also uses Windows-style file sharing. However, when the host and VM both run Linux, and you are using a modern version of Samba (3.x), POSIX file semantics are supported, so there is no loss of functionality (permissions, softlinks, and so on are preserved). Ensure that the samba package is installed from your distribution's package repository and that /etc/samba/smb.conf file exists.

=== Exporting Shares (Manual) ===

'''Method 1'''

If you are in the sambashare group, you may define a user share directly. This is done by adding an entry to /var/lib/samba/usershares (or, to the path defined by the usershare path option in /etc/samba/smb.conf file. Try testparm -s -parameter-name='usershare path' to see the setting).

Add a text file to this directory whose name is the Share name (for example, public). Specify its contents like this:

<nowiki>#VERSION 3
path=/home/localuser/Public
comment=
usershare_acl=S-1-1-0:F
guest_ok=yes
directory mask=755
create mask=644</nowiki>

The share will immediately become available.

If your Samba server is older, you may need to use this format:

<nowiki>#VERSION 2
path=/home/localuser/Public
comment=
usershare_acl=S-1-1-0:F
guest_ok=y</nowiki>

'''Method 2'''

Alternately, you may add the share directly to the Samba configuration. Edit the /etc/samba/smb.conf file as root.

Add an entry like the following to the end of the file:

[Public]
writable = yes
public = yes
browseable = yes
path = /home/localuser/Public

Substitute appropriate values for path and select a custom share name instead of Public in brackets. The bracketed section name is the Share name used in ESbox.

Then restart samba with: $ sudo killall -HUP smbd

=== Exporting Shares (GNOME) ===

Alternately, under GNOME and Nautilus, you may export shares through theUI, by using the '''Sharing Options''' item on a folder's context menu, figure [[#fig:shared_folders_gnome_share_menu|6.31]].

{| summary="Sharing Options"
|+ align="BOTTOM" |'''Figure 6.31:''' Sharing Options
|-
|
[[Image:gnome-share-menu.png|Image gnome-share-menu]]
|}

Check '''Share this folder'''. Type in the '''Share name''' to use (which will serve the same role in the ESbox Shared Folders configuration). If you are using this folder for hosting projects, enable '''Allow other people to write in this folder'''.

You may also need to enable '''Guest access''' if you do not have the same user accounts in the host and VM, figure [[#fig:shared_folders_gnome_share_dialog|6.32]].

{| summary="Folder Sharing"
|+ align="BOTTOM" |'''Figure 6.32:''' Folder Sharing
|-
|
[[Image:gnome-share-dialog.png|Image gnome-share-dialog]]
|}

Such shares are created as user shares, as described above.

== Troubleshooting ==

'''Shared folder configuration problems'''

If you cannot mount to shared folders published from Windows, and you get the error mount error 12 = cannot allocate memory, then this is a host issue. Certain virus scanners may reset a registry setting to an inappropriately low value, making it impossible to export shares. You can fix this in your Windows registry.

Edit the key HKEY_ LOCAL_ MACHINE\System\CurrentControlSet \Services\LanmanServer\Parameters\IRPStackSize. Define it as a DWORD value (if missing). Set it to a value in the decimal range 15 to 18. The documentation is unclear what this value indicates, but it is probably a power-of-two. It may require some experimentation. The new setting will only be read when the sharing service is restarted. You may do this via '''Control Panel > Administrative Tools > Services > Server''' and restart, or if you have got more time to spare, reboot your system.

Also see the [http://support.microsoft.com/default.aspx?scid=kb;en-us;177078 Microsoft Knowledge Base] article for more information.

'''Time synchronzation problems'''

Be careful about the time synchronization configuration in the VM or the timezone used in the VM image.

If you see warnings like:

make: Warning: File Makefile has modification time 1.1e+07 in the future rm -f *.o helloworld make: warning: Clock skew detected. Your build may be incomplete.

then install the appropriate virtualization tools to ensure the time is synchronized.

When using VirtualBox, please install Guest Additions to fix the time synchronization. In VMware, install VMware Tools. Alternately, log into to VM and change the timezone. There is not consistent behaviour between VM engines, so some tweaking may be required. You may need to be connected to a LAN for the PC <-> VM communication to work properly. Otherwise shared folders will not be mountable and you may get mysterious timeouts instead.

If you use Windows and your VM uses NAT, it is unlikely that you are able to mount folders from the VM without significant advanced networking setup effort. You would need to use port forwarding to see ports 139 and 445 from the VM without conflicting with the host's own sharing protocol. Windows does not provide an obvious way to use SMB with different ports and you need to set up some sort of virtual host over SSH to forward SMB traffic.

'''Autotools projects fail to build Makefile'''

If you have created or imported an autotools-based project, and run autoconf and configure, but make reports errors like: <code>make: *** No rule to make target 'all'. Stop.</code> the reason may be compatibility problem between older autoconf versions and Samba shares.

This may be due to a known file truncation issue that occurs when using autoconf 2.62 or older over Samba shares. Due to trying to rename files before closing them, the configure files will be truncated, preventing Makefiles from being generated. Current Maemo SDKs may still ship these old versions of autoconf.

ESbox can repair the autoconf installation in Scratchbox for you if you install it using the Scratchbox 1 installer wizard. Or, if you have an old image or have manually installed Scratchbox 1, you can right-click the Scratchbox node (for example, in '''Window > Preferences > Maemo > Installed Targets''') and select '''Patch autoconf'''. A wizard guides you through the process of repairing the installation.

= Setting up X Server =

== Setting up X Server on Windows ==

ESbox has been tested with the Cygwin/X server. Cygwin/X server is recommended since Cygwin is required also for other functionality like SSH.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' There are serious issues with the Cygwin 1.7 X11 server when used in Windows 7 (or Windows Vista), meaning that Maemo applications crash the server. Use the Cygwin 1.5.25-15 version instead if you encounter issues. See [http://garage.maemo.org/tracker/?func=detail&atid=1420&aid=4897&group_id=192 this bug] for current status.
|}

You do not need to install all of Cygwin to use X server. It is sufficient to download the setup.exe Cygwin installer from the [http://www.cygwin.com/ Cygwin site] and to select the '''X11/xorg-xserver''', '''X11/xinit''' and '''X11/xdpyinfo''' packages.

=== Runtime display requirements for Fremantle SDKs ===

Fremantle requires a 16-bit color depth for the display. Because Cygwin/X X11 server uses the default display depth from the host PC operating system, you will see the following Eclipse dialog if you launch Eclipse IDE in some other than 16-bit display mode, figure [[#fig:x_setup_windows_color_depth_warning|6.33]].

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Fremantle platform requires X11 server to use 16-bit color depth. Because Cygwin X11 server uses the display depth of the Windows desktop, Windows desktop color depth for host PC must be changed to 16-bit, if depth is something different by default.
|}

{| summary="Colour depth warning"
|+ align="BOTTOM" |'''Figure 6.33:''' Colour depth warning
|-
|
[[Image:warning_color_depth.png|Image warning_color_depth]]
|}

Some mouse pointer workarounds in earlier versions of ESbox are no longer needed. If they are still set, you see this dialog asking permission to modify your '''ESbox > X Server''' command launch parameters, figure [[#fig:x_setup_windows_mouse_pointer_warning|6.34]].

{| summary="Mouse pointer warning"
|+ align="BOTTOM" |'''Figure 6.34:''' Mouse pointer warning
|-
|
[[Image:warning_options.png|Image warning_options]]
|}

You can also see the combined warning if both changes are needed, figure [[#fig:x_setup_windows_combined_warning|6.35]].

{| summary="Combined warning"
|+ align="BOTTOM" |'''Figure 6.35:''' Combined warning
|-
|
[[Image:warning_color_depth_options.png|Image warning_color_depth_options]]
|}

=== How to change colour depth in Windows XP ===

Right-click the desktop, and then click '''Properties''', figure [[#fig:x_setup_windows_xp_desktop|6.36]].

{| summary="Windows XP desktop properties"
|+ align="BOTTOM" |'''Figure 6.36:''' Windows XP desktop properties
|-
|
[[Image:xp_desktop.png|Image xp_desktop]]
|}

Click the '''Settings''' tab.

Click the drop-down list in the '''Color Quality''' field and select '''Medium (16 bit)'''.

Click '''OK''', figure [[#fig:x_setup_windows_xp_desktop_properties|6.37]].

{| summary="Windows XP Display Properties"
|+ align="BOTTOM" |'''Figure 6.37:''' Windows XP Display Properties
|-
|
[[Image:xp_display_properties.png|Image xp_display_properties]]
|}

=== How to change colour depth in Windows Vista ===

Right-click the desktop, and then click '''Personalize''', figure [[#fig:x_setup_windows_vista_desktop|6.38]].

{| summary="Windows Vista desktop properties"
|+ align="BOTTOM" |'''Figure 6.38:''' Windows Vista desktop properties
|-
|
[[Image:vista_desktop.png|Image vista_desktop]]
|}

Click the '''Display Settings''', figure [[#fig:x_setup_windows_vista_control_panel|6.39]].

{| summary="Windows Vista Personalization"
|+ align="BOTTOM" |'''Figure 6.39:''' Windows Vista Personalization
|-
|
[[Image:vista_control_panel.png|Image vista_control_panel]]
|}

Click the drop-down list in the '''Colors''' field and select '''Medium (16 bit)'''.

Click '''Ok''', figure [[#fig:x_setup_windows_vista_display_properties|6.40]].

{| summary="Windows Vista Display Settings"
|+ align="BOTTOM" |'''Figure 6.40:''' Windows Vista Display Settings
|-
|
[[Image:vista_display_properties.png|Image vista_display_properties]]
|}

=== How to change the display colour depth in Windows 7 ===

Open the Control panel ('''Start > Control Panel'''), figure [[#fig:x_setup_windows_7_control_panel_menu|6.41]].

{| summary="Windows 7 Start menu"
|+ align="BOTTOM" |'''Figure 6.41:''' Windows 7 Start menu
|-
|
[[Image:7_control_panel_menu.png|Image 7_control_panel_menu]]
|}

Click '''Adjust screen resolution''' under '''Appearance and Personalization''', figure [[#fig:x_setup_windows_7_appearance_personalization|6.42]].

{| summary="Windows 7 Control Panel"
|+ align="BOTTOM" |'''Figure 6.42:''' Windows 7 Control Panel
|-
|
[[Image:7_appearance_personalization.png|Image 7_appearance_personalization]]
|}

Click '''Advanced settings''', figure [[#fig:x_setup_windows_7_screen_resolution|6.43]].

{| summary="Windows 7 Screen Resolution"
|+ align="BOTTOM" |'''Figure 6.43:''' Windows 7 Screen Resolution
|-
|
[[Image:7_screen_resolution.png|Image 7_screen_resolution]]
|}

Click the '''Monitor''' tab, figure [[#fig:x_setup_windows_7_monitor_tab|6.44]].

{| summary="Windows 7 Monitor tab"
|+ align="BOTTOM" |'''Figure 6.44:''' Windows 7 Monitor tab
|-
|
[[Image:7_monitor_tab.png|Image 7_monitor_tab]]
|}

Under '''Colors''', select '''High Color (16 bit)''', and then click '''OK'''.

== Setting up X Server on Mac OS X ==

=== Installing the server ===

The Xephyr server is recommended since it tracks the newest X server extensions used by Fremantle. Find this in the [http://xquartz.macosforge.org/trac/wiki/X112.3.3 Xquartz project].

=== Runtime display requirements for Fremantle SDKs ===

Fremantle requires a 16-bit color depth for the display. Because Xephyr X11 server uses the default display depth from the host PC operating system you will see Eclipse dialog with warning if you launch Eclipse IDE in some other than 16-bit display mode. Set up your host PC display to have '''Thousands''' of colours in the '''System Preferences > Display field'''.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Fremantle platform requires X11 server to use 16-bit color depth. Because Xephyr X11 server uses the display depth of the Mac OS X desktop, Mac OS X desktop color depth for host PC must be changed to 16-bit, if depth is something different by default.
|}

If ESbox notices that you are trying to run X in an incorrect configuration, it asks you to disable the MIT-SHM option, which is a workaround that fixes the issue, figure [[#fig:x_setup_mac_shm_warning|6.45]].

{| summary="MIT-SHM extension warning"
|+ align="BOTTOM" |'''Figure 6.45:''' MIT-SHM extension warning
|-
|
[[Image:shm_warning.png|Image shm_warning]]
|}

Click '''Yes''' to warning above to disable MIT-SHM extension in the command launch pattern in the '''ESbox > X Server''' preference page and restart the server.

Documentation/Maemo Eclipse Tutorial/Installation Methods

2010-04-09T09:04:28Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Installation Methods =

= PC Connectivity =

In order to communicate with your Maemo device, a set of daemons and utilities needs to be installed to the host PC and Maemo device.

Find the complete description and installation instructions on the [http://pc-connectivity.garage.maemo.org/ PC Connectivity project web site] and ''Maemo PC Connectivity Tutorial'' <ref name=r2>Maemo PC Connectivity Tutorial. http://library.maemodocs.nokia.com</ref>.

== Maemo PC Connectivity ==

On the Maemo device, you need the other half of PC Connectivity, Maemo PC Connectivity, containing the servers that match the clients installed on the host PC side with Host PC Connectivity. The Maemo PC Connectivity requires either Diablo or Fremantle based Maemo device (N800, N810 or N900).

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' You can update your Maemo device operating system using the '''File > New > Other > Maemo Installers > Flash Images to Device''' Eclipse IDE wizard or Maemo Flasher-3.5 command line tool.
|}

Install the Maemo PC Connectivity on the Mameo device before installing Maemo ESbox or PluThon Eclipse IDE environments.

== Host PC Connectivity ==

Host PC Connectivity provides host-side software, like SSH and SBRSH clients, Rsync, FTP client, and the TightVNC viewer. These are packaged together conveniently for installation on Linux, Windows, and Mac OS X Intel.

Install the Host PC Connectivity on the host PC before installing Maemo ESbox or PluThon Eclipse IDE environments.

= Installation via Product Archives =

The Product Archives come in two parts: a common archive, containing the bulk of the installation, and an OS-specific archive. If your host OS is not represented, please use Maemo update sites installation for the best results.

The distributed archives can be extracted anywhere on your system to provide a full Eclipse Ganymede SR2 environment with ESbox or PluThon and all its dependencies pre-installed.

The installation from product archives is upgradeable to new versions using Maemo Update Site.

== Product Archives ==

For ESbox download archives from [https://garage.maemo.org/frs/?group_id=192 ESbox Garage project download] page.

For PluThon download archives from [https://garage.maemo.org/frs/?group_id=247 PluThon Garage project download] page.

=== Linux/x86 ===

ESbox archives:

* esbox_2.0.0-R20091216-common.zip
* esbox_2.0.0-R20091216-linux.gtk.x86.zip

PluThon archives:

* pluthon_2.0.0-R20091216-common.zip
* pluthon_2.0.0-R20091216-linux.gtk.x86.zip

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' In Ubuntu 9.10, Fedora 11, or other platforms using GTK+ 2.18 and/or Mozilla xulrunner 1.19, you must launch ESbox with the script esbox.sh and PluThon with the script pluthon.sh included in the archives. Otherwise, Eclipse will fail to start and/or will have erratic UI. See [http://mou.me.uk/2009/10/31/fixing-eclipse-in-ubuntu-9-10-karmic-koala/ this post for GTK+ details] and [http://mou.me.uk/2009/10/31/fixing-eclipse-in-ubuntu-9-10-karmic-koala/ this bug for xulrunner information].
|}

=== Windows/x86 ===

ESbox archives:

* esbox_2.0.0-R20091216-common.zip
* esbox_2.0.0-R20091216-win32.win32.x86.zip

PluThon archives:

* pluthon_2.0.0-R20091216-common.zip
* pluthon_2.0.0-R20091216-win32.win32.x86.zip

=== Mac OS X/Intel ===

ESbox archives:

* esbox_2.0.0-R20091216-common.zip
* esbox_2.0.0-R20091216-macosx.carbon.x86.zip

PluThon archives:

* pluthon_2.0.0-R20091216-common.zip
* pluthon_2.0.0-R20091216-macosx.carbon.x86.zip

== Installing and Running ==

Extract and install the archives for your operating system: Unzip the <nowiki>*-common.zip</nowiki> and <nowiki>*-<host OS>.zip</nowiki> archive into the same directory of your choice.

If you use a Sun Java JRE, you can edit esbox.ini or pluthon.ini to adjust maximum memory usage (-Xmx, -XX:MaxPermSize).

Run the main executable or script:

; '''Linux'''
: ./esbox.sh or ./pluthon.sh
; '''Win32'''
: ./esbox.exe or ./pluthon.exe
; '''Mac OS X'''
: ./esbox.app/Contents/MacOS/esbox or ./pluthon.app/Contents/MacOS/esbox

= Installation via Maemo Update Site =

When you install ESbox, PluThon and Mica components through the Maemo update site, all needed dependencies (like CDT, PyDev, RSE, DSF, etc.) are installed automatically.

== Eclipse Installation ==

If you do not yet have Eclipse IDE installed, follow these instructions.

Download Eclipse Ganymede SR2 (3.4.2) for your host. We suggest a package bundled with CDT:

* [http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/ganymede/SR2/eclipse-cpp-ganymede-SR2-win32.zip Win32]
* [http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/ganymede/SR2/eclipse-cpp-ganymede-SR2-linux-gtk.tar.gz Linux 32-bit]
* [http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/ganymede/SR2/eclipse-cpp-ganymede-SR2-macosx-carbon.tar.gz Max OS X]
* ...or visit the [http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/ganymede/SR2/ Eclipse Ganymede SR2 Build page]. You must use Eclipse 3.4.2.
* The Maemo update site will ensure all needed additional packages are installed, so you can also start from a different Eclipse package.
* Other hosts are not officially supported for Maemo development but you are welcome to try installation or trying to use the Maemo SDK Virtual Image to run Maemo Eclipse development environment.

Extract the archive somewhere on your machine (for example /home/user on Linux).

For Linux or Mac OS X:

$ cd /home/user
$ tar xvzf eclipse-cpp-ganymede-SR2-host-windowsystem.tar.gz

or, for Win32, use Winzip or another zip utility to extract the archive.

Start Eclipse by running the Eclipse executable included with the release. The executable file is called eclipse, and is located in the eclipse sub-directory of the install:

$ /home/user/eclipse/eclipse

In recent Linux distributions like Ubuntu 9.10 or Fedora 11, GTK+ 2.18 and Mozilla's xulrunner have changed in ways that cause problems with Eclipse. See more information about [http://mou.me.uk/2009/10/31/fixing-eclipse-in-ubuntu-9-10-karmic-koala/ GTK+ issues from this email] and [https://garage.maemo.org/tracker/index.php?func=detail&aid=4689&group_id=192&atid=1420 xulrunner issue from this bug report].

If the xulrunner problem affects you, you will need to launch Eclipse as shown below:

$ GDK_NATIVE_WINDOWS=true /home/user/eclipse/eclipse -vmargs -Dorg.eclipse.swt.browser.XULRunnerPath=path...

where path... is the path to xulrunner 1.8, usually under /usr/lib/xulrunner/xulrunner or /usr/bin/xulrunner. In Ubuntu this package is named xulrunner.

See [http://mou.me.uk/2009/10/31/fixing-eclipse-in-ubuntu-9-10-karmic-koala/ this post for GTK+ details] and [https://garage.maemo.org/tracker/index.php?func=detail&aid=4689&group_id=192&atid=1420 this bug for xulrunner information].

For the sake of convenience, there are ready made scripts available to use for ESbox and PluThon that implement this workaround. For ESbox, use [https://garage.maemo.org/svn/mica/build/continuous_integration/esbox.sh this] esbox.sh script and for PluThon, use [https://garage.maemo.org/svn/mica/build/continuous_integration/pluthon.sh this] pluthon.sh script to launch Eclipse IDE.

For more detailed information about Eclipse 3.4 environment, see the [http://www.eclipse.org/eclipse/development/readme_eclipse_3.4.2.html Eclipse 3.4.2 Project Release Notes].

== ESbox and PluThon Installation ==

Verify that your network proxy is configured (if needed) in '''Window > Preferences > General > Network Connections'''.

Select '''Help > Software Updates...''' from the main menu bar, figure [[#fig:update_site_update_menu|3.1]].

These instructions given are for ESbox installation through the Maemo Update Site, but can also be applied for the PluThon installation.

{| summary="Software Updates"
|+ align="BOTTOM" |'''Figure 3.1:''' Software Updates
|-
|
[[Image:esbox-update-menu.png|Image esbox-update-menu]]
|}

Select the '''Available Software''' tab, figure [[#fig:update_site_update_available|3.2]].

{| summary="Software Updates and Add-ons"
|+ align="BOTTOM" |'''Figure 3.2:''' Software Updates and Add-ons
|-
|
[[Image:esbox-update-available.png|Image esbox-update-available]]
|}

Add three update sites via '''Add site....'''

* ESbox update site is: http://maemoide.nokia.com/updates/2.0/esbox, figure [[#fig:update_site_add_esbox|3.3]].
* PluThon update site is: http://maemoide.nokia.com/updates/2.0/pluthon.
* Mica update site is: http://maemoide.nokia.com/updates/2.0/mica, figure [[#fig:update_site_add_mica|3.4]].

Example how to add ESbox update site:

{| summary="Update Site, Add ESbox"
|+ align="BOTTOM" |'''Figure 3.3:''' Update Site, Add ESbox
|-
|
[[Image:esbox-update-site-add-esbox.png|Image esbox-update-site-add-esbox]]
|}

Example how to add Mica update site:

{| summary="Update Site, Add Mica"
|+ align="BOTTOM" |'''Figure 3.4:''' Update Site, Add Mica
|-
|
[[Image:esbox-update-site-add-mica.png|Image esbox-update-site-add-mica]]
|}

Mica is a generic framework named Maemo IDE Common Architecture underneath the ESbox and PluThon products.

Open the '''ESbox''' (or '''PluThon''') tree and select '''ESbox 2nd Edition''' (or '''PluThon 2nd Edition''') inside, then click '''Install''', figure [[#fig:update_site_selection|3.5]].

{| summary="Software Updates and Add-ons, ESbox 2nd Edition"
|+ align="BOTTOM" |'''Figure 3.5:''' Software Updates and Add-ons, ESbox 2nd Edition
|-
|
[[Image:esbox-update-selection.png|Image esbox-update-selection]]
|}

You can select the '''ESbox 2nd Edition Source''', '''PluThon 2nd Edition Source''' and '''Mica 2nd Edition Source''' as well as following the [http://mica.garage.maemo.org/2nd_edition/setup.html Mica development setup instructions] if you want to develop against ESbox or PluThon.

Verify the installed items, then click '''Next''', figure [[#fig:update_site_install|3.6]].

{| summary="Install"
|+ align="BOTTOM" |'''Figure 3.6:''' Install
|-
|
[[Image:esbox-update-install.png|Image esbox-update-install]]
|}

Review the licenses, then click '''Next''', figure [[#fig:update_site_install_licenses|3.7]].

{| summary="Review licenses"
|+ align="BOTTOM" |'''Figure 3.7:''' Review licenses
|-
|
[[Image:esbox-update-install-licenses.png|Image esbox-update-install-licenses]]
|}

The '''ESbox 2nd Edition''' selection brings in everything from ESbox and Mica, and the '''PluThon 2nd Edition''' selection brings in everything from PluThon and Mica. You can individually select the items under the '''ESbox''', '''PluThon''' and '''Mica''' nodes on the '''Available Software''' page, if you desire. This will make it easier to uninstall individual components later.

Click '''Finish''' and the installation will be performed. Accept the offer to restart Eclipse, figure [[#fig:update_site_restart|3.8]].

{| summary="Restart Eclipse"
|+ align="BOTTOM" |'''Figure 3.8:''' Restart Eclipse
|-
|
[[Image:esbox-update-restart.png|Image esbox-update-restart]]
|}

== Updating from an earlier than R2.0.0 release ==

If you used the archive files for installation, you can follow the instructions below to update your installation to the latest ESbox or PluThon version.

Select '''Help > Software Updates...''' from the main menu bar, figure [[#fig:update_site_update_menu_2|3.9]].

{| summary="Software Updates"
|+ align="BOTTOM" |'''Figure 3.9:''' Software Updates
|-
|
[[Image:esbox-update-menu.png|Image esbox-update-menu]]
|}

If you installed directly from a repository archive (<nowiki>*.zip</nowiki>) file, rather than from the web, follow the below steps first:

# Select the '''Available Software''' tab.
# Click the '''Manage Repositories...''' button.
# Remove the old archive entries (esbox-repository*.zip, pluthon-repository*.zip, mica-repository*.zip)
# Add new update sites through '''Add site...''' pointing to the new repository archives.

Select the '''Installed Software''' tab, figure [[#fig:update_site_update_installed|3.10]].

{| summary="Installed Software"
|+ align="BOTTOM" |'''Figure 3.10:''' Installed Software
|-
|
[[Image:esbox-update-installed.png|Image esbox-update-installed]]
|}

Click the '''Update...''' button.

Eclipse should display an '''Operation in progress...''' dialog and take a little time to query the configured update sites and should find the new versions of ESbox, PluThon and Mica features (as well as possibly other installed features).

Verify that ESbox, PluThon and Mica features are listed and checked, then click '''Next''', figure [[#fig:update_site_update_available_2|3.11]].

{| summary="Available Updates"
|+ align="BOTTOM" |'''Figure 3.11:''' Available Updates
|-
|
[[Image:esbox-update-available-2.png|Image esbox-update-available-2]]
|}

Review the licenses, then click '''Next''', figure [[#fig:update_site_update_licenses|3.12]].

{| summary="Review licenses"
|+ align="BOTTOM" |'''Figure 3.12:''' Review licenses
|-
|
[[Image:esbox-update-install-licenses.png|Image esbox-update-install-licenses]]
|}

Click '''Finish''' and the update is performed. Accept the offer to restart Eclipse, figure [[#fig:update_site_restart_2|3.13]].

{| summary="Restart Eclipse"
|+ align="BOTTOM" |'''Figure 3.13:''' Restart Eclipse
|-
|
[[Image:esbox-update-restart.png|Image esbox-update-restart]]
|}

== Troubleshooting ==

If you see this dialog: figure [[#fig:update_site_can_not_complete|3.14]]

{| summary="Cannot complete the request"
|+ align="BOTTOM" |'''Figure 3.14:''' Cannot complete the request
|-
|
[[Image:esbox-update-cannot-complete.png|Image esbox-update-cannot-complete]]
|}

followed by this dialog: figure [[#fig:update_site_already_installed|3.15]]

{| summary="Cannot complete the request, details"
|+ align="BOTTOM" |'''Figure 3.15:''' Cannot complete the request, details
|-
|
[[Image:esbox-update-already-installed.png|Image esbox-update-already-installed]]
|}

Messages about '''Cannot find a solution...''' usually means the given features or plugins are already installed, or that older versions were installed from a different site. Try using '''Software Updates... > Installed Software > Update...''' instead.

If you have an older ESbox or PluThon installation with features and plugins installed from another URL, use '''Software Updates... > Installed Software > Uninstall...''' to remove the ESbox or PluThon installation. This may make Eclipse unlaunchable - if so, launch Eclipse as shown below:

$ ./esbox.sh -application org.eclipse.sdk.ide

until Eclipse is reinstalled from the current location.

= Installing Help Content =

Both ESbox and PluThon support the use of Maemo release documentation from the Eclipse IDE, both remotely and locally. You can configure the Eclipse environment to access Maemo online release documentation from the Maemo Info Center service. The same documentation available from the Maemo Info Center can also be downloaded to the host PC and installed locally on the Eclipse help system.

== Remote Help Content ==

The Mica framework included in ESbox and PluThon can use the Eclipse hover remote help system to access online documentation. For Maemo platform releases, the online documentation for each release is available from [http://maemoide.nokia.com/ Maemo Info Center service].

For more information about Hover help, see the ESbox or the PluThon Help topic '''Getting Started > Using Hover Help for Maemo API Libraries'''.

You need to configure the Maemo Info Center to use the Maemo 5 Fremantle SDK help inside Eclipse:

Open the '''Help > Content''' preference page, figure [[#fig:update_site_help_infocenter_prefs|3.16]].

{| summary="Help Content Preferences"
|+ align="BOTTOM" |'''Figure 3.16:''' Help Content Preferences
|-
|
[[Image:help-infocenter-prefs.png|Image help-infocenter-prefs]]
|}

Add a Maemo Info Center site, noting to update the host (no http:// prefix) and the path, which is Maemo platform specific (/fremantle for Maemo 5 Fremantle release), figure [[#fig:update_site_help_infocenter_prefs_add|3.17]].

{| summary="Edit Maemo Docs Library Information"
|+ align="BOTTOM" |'''Figure 3.17:''' Edit Maemo Docs Library Information
|-
|
[[Image:help-infocenter-prefs-add.png|Image help-infocenter-prefs-add]]
|}

Then, use '''Help > Content''' and you will see the entries under '''Maemo 5''' categories.

== Local Content ==

If you prefer, you may also install all Maemo release documentation locally so that no network connection is needed when accessing Maemo documentation. Locally installed documentation is also faster to access and search than online documentation from the Maemo Info Center.

This content is only available from the Maemo update site. You can also install Maemo release documentation locally in case you installed ESbox or PluThon from a full-product archive instead of Maemo update site.

These instructions assume you have already installed the Eclipse ESBox or PluThon product using either Maemo Eclipse product archives or update sites.

Verify that your network proxy is configured (if needed) in '''Window > Preferences > General > Network Connections'''.

Select '''Help > Software Updates...''' from the main menu bar, figure [[#fig:update_site_help_pluthon_update_menu|3.18]].

{| summary="Software Updates..."
|+ align="BOTTOM" |'''Figure 3.18:''' Software Updates...
|-
|
[[Image:pluthon-update-menu.png|Image pluthon-update-menu]]
|}

Select the '''Available Software''' tab, figure [[#fig:update_site_help_update_available|3.19]].

{| summary="Software Updates and Add-ons"
|+ align="BOTTOM" |'''Figure 3.19:''' Software Updates and Add-ons
|-
|
[[Image:help-update-available.png|Image help-update-available]]
|}

Add a Documentation update site via '''Add site....'''. Maemo Fremantle documentation update site is http://maemoide.nokia.com/downloads/fremantle/, figure [[#fig:update_site_help_update_site_add|3.20]].

{| summary="Update Site - Add Documentation"
|+ align="BOTTOM" |'''Figure 3.20:''' Update Site - Add Documentation
|-
|
[[Image:help-update-site-add.png|Image help-update-site-add]]
|}

Select one or more of the '''Maemo ... Help''' features and then click ''''''Install, figure [[#fig:update_site_help_update_selection|3.21]].

{| summary="Software Updates and Add-Ons, Selection"
|+ align="BOTTOM" |'''Figure 3.21:''' Software Updates and Add-Ons, Selection
|-
|
[[Image:help-update-selection.png|Image help-update-selection]]
|}

Verify the installed items, then click '''Next''', figure [[#fig:update_site_help_update_install|3.22]].

{| summary="Confirm Installation"
|+ align="BOTTOM" |'''Figure 3.22:''' Confirm Installation
|-
|
[[Image:help-update-install.png|Image help-update-install]]
|}

Review the licenses, then click '''Next''', figure [[#fig:update_site_help_update_install_licenses|3.23]].

{| summary="Accept Licenses"
|+ align="BOTTOM" |'''Figure 3.23:''' Accept Licenses
|-
|
[[Image:help-update-install-licenses.png|Image help-update-install-licenses]]
|}

Click '''Finish''' and the installation is performed. You may be able to '''Apply Changes''' if you have not already opened help or turned on hover help. Otherwise accept the offer to restart Eclipse, figure [[#fig:update_site_help_pluthon_update_restart|3.24]].

{| summary="Apply Changes Or Restart"
|+ align="BOTTOM" |'''Figure 3.24:''' Apply Changes Or Restart
|-
|
[[Image:pluthon-update-restart.png|Image pluthon-update-restart]]
|}

== References ==
<references />

Documentation/Maemo Eclipse Tutorial/Introduction

2010-04-09T09:04:27Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Introduction =

Instead of using the Maemo development environment command line tools to create C/C++, Python or Qt applications for the Maemo platform, it is possible to use an Eclipse, Ganymede-based IDE to make applications development easier for Maemo devices.

Maemo Eclipse IDE integration supports following Maemo devices and platform releases:

* Nokia N800, N810 and N810 WiMAX Edition with Diablo 4.1.x.
* Nokia N900 with Fremantle 5.x, see figure [[#fig:eclipse-tutorial-introduction-n900|1.1]].

{| summary="Maemo device - N900"
|+ align="BOTTOM" |'''Figure 1.1:''' Maemo device - N900
|-
|
[[Image:Nokia_N900_38.png|Image Nokia_N900_38]]
|}

Maemo Eclipse support includes the ESbox product that supports C/C++, Python and Qt programming together with Maemo SDK and Maemo devices. ESBox has full integration to both the Scratchbox-based Maemo SDK environment and Maemo devices.

In addition to the ESbox product, Maemo Eclipse integration provides also the PluThon product that supports Python development with Maemo devices. The PluThon environment does not use Maemo SDK but is an on-device development environment where Python application development happens directly within the Maemo device.

Both ESbox and PluThon can be used on all major platforms (Linux, Windows and Mac OS X). On all supported operating systems Eclipse IDE is run natively on host PC. On Debian-based Linux systems the Maemo SDK can be installed antively to the host PC. On other Linux variants (like Fedora) and non-Linux systems (like Windows and Mac OS X) where the Maemo SDK cannot be installed, it is possible to use a virtual machine or a remote Debian based Linux system to host the Maemo SDK. ESbox will translate all IDE UI commands to SDK commands behind the scenes.

ESbox and PluThon run inside Eclipse with CDT (C/C++ Development Tools) installed. The Eclipse environment requires a Java virtual machine to run properly; JavaTMPlatform, Standard Edition 6 (JavaTMSE 6) or above is recommended. ESbox also needs Scratchbox and Maemo SDK targets for building components and developing applications.

Note that ESbox has native support to develop also Qt applications. This makes the development of Qt applications easier than using Maemo SDK only, since no command line execution is required to build and execute the application in the Maemo SDK target or Maemo device.

Maemo Eclipse integration has support for basic profiling tools for Maemo applications development. Profiling is one of the most important techniques available for programmers for discovering problems in applications. By profiling an application, it becomes immediately apparent where the overwhelming memory and CPU burdens exist, and allows you to quickly correct them. Maemo Eclipse provides support for the Valgrind memory profiler, the OProfile system-wide profiler and the Ltrace library call monitor for both C/C++ and Python Projects.

Ltrace is a tracing tool which runs a specified tracing for an application or a library. While the tool is executing, ltrace intercepts and records the dynamic library calls which are called by the executed process and the signals received by that process. On a Maemo environment, Ltrace is supported on both a Maemo SDK x86 target and a Maemo device.

Eclipse Ltrace support launches your application on the Maemo SDK target or the Maemo device for tracing, and the result is shown in specific Ltrace view. All Library and System calls are shown as a tree: parent nodes and child nodes for each new nested call.

Valgrind is a framework for building dynamic analysis tools. You can use Valgrind to profile your applications. It detects memory management (memory leaks, use of uninitialised memory, and so forth) and thread bugs. For Maemo, Valgrind is only supported on X86/Linux and thus only on the Maemo SDK x86 target. To be able to use Valgrind profiling you have to select a X86 Scratchbox target to run your application.

Eclipse Valgrind support runs your application on the the X86 target and the result is shown on a specific Valgrind view. All problems found by Valgrind are shown as a tree: the problems as parent nodes and the details of the problems as children nodes.

OProfile is a system-wide profiler for Linux systems and can profile all running code. It consists of a kernel driver and a daemon for collecting sample data, and several post-profiling tools for turning data into information. On the Maemo environment OProfile is supported only on Maemo devices to obtain a high quality of profiling information. Eclipse uses ssh to remotely execute the OProfile and collect profiling information on the Maemo device. Thus, it is necessary to properly install the application to be profiled and the OProfile framework on the Maemo device before the profiling can be done.

The Eclipse OProfile support runs your application on the Maemo device, and you can control the OProfile from the Eclipse OProfile view. After the OProfile has stopped the profiling, the result will be shown in the specific OProfile View.

----

Documentation/Maemo Eclipse Tutorial/Installing ESbox

2010-04-09T09:04:26Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Installing ESbox =

ESbox is an [http://www.eclipse.org/ 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'' <ref name=r2>Maemo PC Connectivity Tutorial. http://library.maemodocs.nokia.com</ref>.

= 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 [[#Supported Environments]] describes these. The "Installing ESbox IDE" section [[#Installing ESbox IDE]] describes how to install ESbox.

== Supported Maemo Releases ==

The supported [http://tablets-dev.nokia.com/ Maemo releases] are:

* Maemo 4.1.2 Diablo (OS2008) with N800, N810 and N810 WiMAX Edition devices
* Maemo 5.0 Fremantle (OS2009) with N900 device

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' 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.
|}

=== 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.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' 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

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' 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'''.

== 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 [http://maemo.org/development/sdks/ 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.

=== 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 [http://maemovmware.garage.maemo.org/ 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 chapter [/node8.html#sec:esbox_installation_setting_up_esbox_using_a_virtual_machine 6.1]) so that ESbox knows where to install Scratchbox and the Maemo SDKs.

The "Supported Environments" chapter [[#Supported Environments]] 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.

= Supported Environments =

== 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, e.g. Maemo does not provide official support for any 64-bit operating system.

{| border="1" cellpadding="3"
|+ '''Table 5.1:''' Host Operating Systems Supported for ESbox
|-
! width="200" align="LEFT" valign="TOP" | '''Host Operating System'''
! width="75" align="LEFT" valign="TOP" | '''Officially Supported'''
! width="75" align="LEFT" valign="TOP" | '''Virtual Image Required'''
! width="50" align="LEFT" valign="TOP" | '''Tested'''
! width="50" align="LEFT" valign="TOP" | '''Note'''
|-
| width="200" align="LEFT" valign="TOP" | Ubuntu 8.04 Hardy
| width="75" align="LEFT" valign="TOP" | Yes
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Ubuntu 8.10 Intrepid
| width="75" align="LEFT" valign="TOP" | Yes
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Ubuntu 9.04 Jaunty
| width="75" align="LEFT" valign="TOP" | Yes
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Ubuntu 9.10 Karmic
| width="75" align="LEFT" valign="TOP" | Yes
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | 3
|-
| width="200" align="LEFT" valign="TOP" | Fedora 11/12
| width="75" align="LEFT" valign="TOP" | No
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | 1,3
|-
| width="200" align="LEFT" valign="TOP" | Other Linux distros
| width="75" align="LEFT" valign="TOP" | No
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | 1,2
|-
| width="200" align="LEFT" valign="TOP" | Windows XP SP3
| width="75" align="LEFT" valign="TOP" | Yes
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Windows Vista SP2
| width="75" align="LEFT" valign="TOP" | No
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | 2
|-
| width="200" align="LEFT" valign="TOP" | Windows 7
| width="75" align="LEFT" valign="TOP" | No
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | 2
|-
| width="200" align="LEFT" valign="TOP" | Mac OS X x86 Leopard
| width="75" align="LEFT" valign="TOP" | Yes
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Mac OS X x86 Snow Leopard
| width="75" align="LEFT" valign="TOP" | Yes
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Mac OS X PPC Leopard
| width="75" align="LEFT" valign="TOP" | No
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | 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 esbox.sh script to launch ESbox and work around the issues.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' 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.
|}

== 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.

=== 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 <nowiki>*.vmx</nowiki> 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 e.g. memory size can be configured without hand-editing <nowiki>*.vmx</nowiki> 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.

=== Sun VirtualBox 2.2 or Newer ===

VirtualBox performance is almost egual 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.

=== 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.

== 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.

= Installing ESbox IDE =

== Java Runtime ==

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

Eclipse 3.4.2 requires Java 1.5 or newer:

* [http://java.sun.com/javase/downloads/index_jdk5.jsp Sun Java 5.0] or [http://java.sun.com/javase/downloads/index.jsp Sun Java 6]
* [http://www.ibm.com/developerworks/java/jdk/index.html IBM JRE 5.0+]
* [http://openjdk.java.net/ OpenJDK 6+]

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' GNU gcj is not supported.
|}

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

== 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 these instructions [/node5.html#sec:eclipse_tutorial_installation_product_archives 3.2]

== 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 these instructions [/node5.html#sec:eclipse_tutorial_installation_via_update_site 3.3]

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Both the installation via the Full Product Archive and the Eclipse Update Site can be upgraded using Eclipse's Software Updates.
|}
== References ==
<references />

Documentation/Maemo Eclipse Tutorial/Bibliography

2010-04-09T09:04:26Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

== Bibliography ==

; 1
: Ltrace Man Page. <tt>http://linux.die.net/man/1/ltrace</tt>.
; 2
: Maemo PC Connectivity Tutorial. <tt>http://library.maemodocs.nokia.com</tt>.
; 3
: OProfiling with Maemo. <tt>http://maemo.org/development/tools/doc/diablo/oprofile/</tt>.
; 4
: OProfile Manual. <tt>http://oprofile.sourceforge.net/doc/index.html</tt>.
; 5
: Valgrind Manual. <tt>http://valgrind.org/docs/manual/manual.html</tt>.

----

Documentation/Maemo Eclipse Tutorial/Installing PluThon

2010-04-09T09:04:25Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Installing PluThon =

PluThon is an [http://www.eclipse.org Eclipse-based IDE] that provides Python development support, source editing, project building, on-device run/debug/profiling as well as on-device Debian installation package creation and deployment. It is based on Eclipse Ganymede (3.4.2) and PyDev (Python IDE for Eclipse). PluThon communicates with your Maemo device using the various network clients and servers that Maemo PC Connectivity project provides.

With PluThon and Maemo PC Connectivity installed, you can flash your Maemo device, run, debug, and profile Python applications on Maemo devices. You can also create Debian installation packages for your application and install the application on 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'' <ref name=r2>Maemo PC Connectivity Tutorial. http://library.maemodocs.nokia.com</ref>.

= PluThon IDE =

You can install PluThon completely from an archive or add it to an existing Eclipse 3.4.2 installation through Maemo update sites.

You can install PluThon on a variety of hosts. The "Supported Environments" section [[#Supported Environments]] describes the supported hosts. The "Installing PluThon IDE" section [[#Installing PluThon IDE]] describes how to install PluThon.

== Supported Maemo Releases ==

The supported [http://tablets-dev.nokia.com/ Maemo releases] are:

* Maemo 4.1.2 Diablo (OS2008) with N800, N810, and N810 WiMAX Edition
* Maemo 5.0 Fremantle (OS2009) with N900

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' 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.
|}

== PluThon Development Environment ==

The PluThon development environment consists of Eclipse IDE and a Maemo device. These are essential and you cannot use PluThon without them.

Even though PluThon deploys applications that run entirely on a device, you need a Python interpreter installed locally to support the editor and the run/debug mechanism in PyDev.

It is recommended that you use the same version of Python that is on the Maemo device, currently Python 2.5. For more information, see the instructions [http://www.python.org/download/releases/2.5.4/ at Python 2.5.4 official release]. PluThon configures PyDev to read the library sources of the host for code completion. If you are not concerned about differences, you can also install Python 2.4 or 2.6 on the host.

Python runtime and bindings libraries must be installed on the Maemo device. To install these, select '''Project > Validate Installed Packages'''. This validation operation is also done automatically when you create a new Python project.

= Supported Environments =

== Host Operating Systems Supported ==

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

{| border="1" cellpadding="3"
|+ '''Table 4.1:''' Host Operating Systems Supported for Pluthon
|-
! width="200" align="LEFT" valign="TOP" | '''Host Operating System'''
! width="75" align="LEFT" valign="TOP" | '''Officially Supported'''
! width="50" align="LEFT" valign="TOP" | '''Tested'''
! width="50" align="LEFT" valign="TOP" | '''Note'''
|-
| width="200" align="LEFT" valign="TOP" | Ubuntu 8.04 Hardy
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Ubuntu 8.10 Intrepid
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Ubuntu 9.04 Jaunty
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Ubuntu 9.10 Karmic
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | 3
|-
| width="200" align="LEFT" valign="TOP" | Fedora 11/12
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | 1,3
|-
| width="200" align="LEFT" valign="TOP" | Other Linux distros
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | 1,2
|-
| width="200" align="LEFT" valign="TOP" | Windows XP SP3
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Windows Vista SP2
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | 2
|-
| width="200" align="LEFT" valign="TOP" | Windows 7
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | 2
|-
| width="200" align="LEFT" valign="TOP" | Mac OS X x86 Leopard
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Mac OS X x86 Snow Leopard
| width="75" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" | Yes
| width="50" align="LEFT" valign="TOP" |
|-
| width="200" align="LEFT" valign="TOP" | Mac OS X PPC Leopard
| width="75" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | No
| width="50" align="LEFT" valign="TOP" | 1,2
|}

; '''Note 1'''
: PluThon should work if Eclipse IDE and Host PC Connectivity runs properly.
; '''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 pluthon.sh script to launch ESbox and work around the issues.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' 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.
|}

= Installing PluThon IDE =

== Java Runtime ==

Eclipse 3.4.2 requires Java 1.5 or newer:

* [http://java.sun.com/javase/downloads/index_jdk5.jsp Sun Java 5.0] or [http://java.sun.com/javase/downloads/index.jsp Sun Java 6]
* [http://www.ibm.com/developerworks/java/jdk/index.html IBM JRE 5.0+]
* [http://openjdk.java.net/ OpenJDK 6+]

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' GNU gcj is not supported.
|}

These JREs are available as packages in your distribution or you can download them directly from the above websites.

== Method 1: Full Product Archive (Recommended) ==

* PluThon is distributed as a full Eclipse product archive that contains Eclipse, the Mica framework, and PluThon. This is the easiest way to ensure you have the right versions of the plugins and features.
* Download the product archive, extract it, and get started. Follow these instructions [/node5.html#sec:eclipse_tutorial_installation_product_archives 3.2]

== Method 2: Eclipse Update Site ==

* If you already have a custom Eclipse 3.4.2 installation or want to build one, you can use the Eclipse Software Updates mechanism to download, install and upgrade PluThon and Mica from the Internet.
* Newer versions of Eclipse than 3.4.x are not supported because of the hard dependencies on the Eclipse packages used.
* Follow these instructions [/node5.html#sec:eclipse_tutorial_installation_via_update_site 3.3]

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' You can upgrade the installation (done either using Full Product Archive or the Eclipse Update Site) through Eclipse Software Updates.
|}

== References ==
<references />

Documentation/Maemo Eclipse Tutorial/Eclipse Tracing

2010-04-09T09:04:24Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Eclipse Tracing =

= Introduction =

IDE Integration provides support for Ltrace library call monitor profiling, available for ESbox and PluThon products. This tutorial presents a brief introduction to Ltrace and shows how to profile your applications at ESbox and PluThon using the Ltrace. Furthermore, it helps you understand how to interpret Ltrace debugging results.

In some cases, it might be useful to verify which are system calls and signals involved during a certain application execution. Ltrace is a profiling tool, which runs a specified command until it exits. While the command is executing, Ltrace intercepts and records the dynamic library calls, which are called by the executed process and the signals received by that process. It can also monitor system calls used by a program.

= Ltrace and Eclipse IDE Integration =

Maemo Eclipse IDE integration products (ESbox and PluThon) provide support for Ltrace tool for C/C++, Qt4 and Python projects on Maemo SDK and device environments. ESbox and PluThon use the command ltrace -S -T to run Ltrace: -S option to display system calls as well as library calls and -T option to show the time spent inside each call. There are other options for Ltrace not used at IDE Integration, they can be found at <ref name=r1>Ltrace Man Page. http://linux.die.net/man/1/ltrace</ref>. This section shows how to profile your applications at ESbox and PluThon and how to analyse profiling results.

== Profiling your Maemo application with Ltrace ==

At first, you must create a C/C++, Qt4 or Python Maemo Project and select the target. After that, run the application with the Ltrace tool. The running can be local and remote for ESbox projects and remote for PluThon projects, as shown below.

=== Local Ltrace Profiling ===

To locally run LTrace on ESbox, right-click on the application (binary for C/C++ and Qt4 projects or the Python script for Python projects) and select '''Profile As > Local Ltrace Profiler''', figure [[#fig:eclipse_tracing_ltrace-menu-local|9.1]]. If the ltrace tool is not properly installed at the selected target, the system can automatically install it, figure [[#fig:eclipse_tracing_install-ltrace|9.2]].

{| summary="Locally Profiling application with Ltrace"
|+ align="BOTTOM" |'''Figure 9.1:''' Locally Profiling application with Ltrace
|-
|
[[Image:ltrace-menu-local.png|Image ltrace-menu-local]]
|}

{| summary="Installing Ltrace at target"
|+ align="BOTTOM" |'''Figure 9.2:''' Installing Ltrace at target
|-
|
[[Image:install-ltrace.png|Image install-ltrace]]
|}

After Ltrace starts, ESbox launches your application on the SDK target and the result is shown in the Ltrace view, figure [[#fig:eclipse_tracing_ltrace-view-local|9.3]].

{| summary="Local Ltrace View"
|+ align="BOTTOM" |'''Figure 9.3:''' Local Ltrace View
|-
|
[[Image:ltrace-view-local.png|Image ltrace-view-local]]
|}

All library and system calls are shown as a table tree: parent nodes representing initial library or system calls and child nodes for each new nested call. Each node or line has four columns: Order, Call, Exit code and Time. By clicking on any column headers you can sort the lines by that column, and if you click again on the same column the sorter direction is inverted. Column '''Order''' is used as default sorter column.

=== Remote Ltrace Profiling ===

To remotely run LTrace on PluThon (or ESbox), right-click on the Python project and select '''Profile As > PluThon Remote Ltrace Python Profiler''', figure [[#fig:eclipse_tracing_ltrace-menu-remote|9.4]].

{| summary="Remotely Profiling application with Ltrace"
|+ align="BOTTOM" |'''Figure 9.4:''' Remotely Profiling application with Ltrace
|-
|
[[Image:ltrace-menu-remote.png|Image ltrace-menu-remote]]
|}

After Ltrace starts, PluThon launches your application on the Device and the result is shown in the Ltrace view as described before, figure [[#fig:eclipse_tracing_ltrace-view-remote|9.5]].

{| summary="Remote Ltrace View"
|+ align="BOTTOM" |'''Figure 9.5:''' Remote Ltrace View
|-
|
[[Image:ltrace-view-remote.png|Image ltrace-view-remote]]
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' If you are planning to run the Ltrace profiler more than once, you do not have to worry about cleaning current Ltrace view results, because this is done automatically before each new profiling. However, if you need to clean the Ltrace view during the profiling, you just need to click '''Delete Current ltrace lines''' button on the Ltrace view toolbar, so the view is reset and keeps receiving current ltrace results.
|}

== Analyzing results ==

During Ltrace profiling, all library and system calls are monitored and listed as a new node/line at Ltrace view. Each line has four columns:

* Order: the position of the call in the table tree view. This column restarts for each nested call.
* Description: the description of the library or system call.
* Exit: exit code of the call.
* Time: the time spent inside the call. This records the time difference between the beginning and the end of the call.

Let us analyse an Ltrace profiling using a Python Project at target <code>DIABLO_X86</code>. After running the Python project with Ltrace you see the following results at Ltrace view, figure [[#fig:eclipse_tracing_ltrace-results-1|9.6]].

{| summary="Ltrace results - initial lines"
|+ align="BOTTOM" |'''Figure 9.6:''' Ltrace results - initial lines
|-
|
[[Image:ltrace-results-1.png|Image ltrace-results-1]]
|}

First, on the initial lines, we can see some system calls indicating that the program is being linked and loaded. For example, line 6 represents a system call named <code>SYS_open</code> that exited with code -2 and took 0.000018 seconds to finish.

{| summary="Ltrace results - program's main statement"
|+ align="BOTTOM" |'''Figure 9.7:''' Ltrace results - program's main statement
|-
|
[[Image:ltrace-results-2.png|Image ltrace-results-2]]
|}

From the latest Ltrace lines (figure [[#fig:eclipse_tracing_ltrace-results-2|9.7]]) we can see at line 85 that the program reached the main statement, called <code>__libc_start_main</code>. Notice also that the main statement has children nodes, that is, it has called another nested call (<code>PY_Main</code>) that has called another nested calls, and so on.

== References ==
<references />

Documentation/Maemo Eclipse Tutorial/Eclipse Memory Profiling

2010-04-09T09:04:24Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Eclipse Memory Profiling =

= Introduction =

Even if a developer provides an extensible round of tests, a certain type of problems cannot be easily detected by unit tests. In addition, such kind of problems may break the application and also disturb the normal execution of the platform. For example, a memory leak is a potential problem on applications for mobile devices, because it certainly consumes an important and limited resource. Maemo SDK provides Valgrind, a profiling tool often used to detect memory-related errors, such as memory leaks and problems on memory allocation.

Maemo IDE integration ESbox product provides support for profiling applications by using Valgrind memory profiler. This tutorial starts with a quick introduction to the Valgrind profiling tool. After that, it demonstrates how you can profile C/C++, Qt4 and Python applications at ESbox using the Valgrind memory profiler tool integration. Finally, you can see how to interpret Valgrind output at ESbox.

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Valgrind memory profiling cannot be used with Maemo PluThon Eclipse IDE. Valgrind profiler be run only with Scratchbox and Maemo SDK for x86 binaries and Maemo PluThon does not support those (it is on-device development environment for Maemo devices).
|}

= Valgrind Memory Profiling =

Valgrind is an Open Source suite of tools for debugging and profiling Linux programs. For Maemo environment it i susable only for x86 binaries. It is a powerful and easy-to-use tool that can save you a lot of debugging time. Since Valgrind works by simulating the x86 processor and instrumenting the binaries on the fly, it can control the program execution completely. On the downside, it makes program execution 10-300 times slower than normal, depending on the used Valgrind tools, and can take a huge amount of memory.

The Valgrind tool suite provides a number of debugging and profiling tools:

; '''Cachegrind'''
: It is a profiler for cache memory. Cachegrind performs simulation of the I1, D1 and L2 caches in order to detect cache misses, wrong references and much more.
; '''Callgrind'''
: It is an extension of Cachegrind. It provides the same information as Cachegrind plus extra information about callgraphs.
; '''Massif'''
: It provides profilling information about heap memory by taking regular snapshots of a program's heap.
; '''Helgrind'''
: It is a useful tool to detect race conditions on multithreading applications, such as deadlocks.
; '''Memcheck'''
: It detects memory-management bugs on application. Memcheck keeps track of the validity (if a memory location is properly initialized) and addressability (if the memory address points to a valid memory block).

Since Valgrind tools instrument the code in order to obtain more accurate information about application execution, Memcheck is often used because it provides detailed information about memory problems, which are very common in mobile application development. It can detect many memory-related errors that are common in C and C++ programs and that can lead to crashes and unpredictable behaviour. Memcheck is the default tool on Maemo environment. The -leak-check option turns on the detailed memory leak detector. Memcheck will issue messages about memory errors and leaks that it detects.

= Valgrind and IDE Integration =

ESbox provides support only for the Valgrind memory (Memcheck) profiler tool for C/C++, Qt4 and Python projects. It uses the command valgrind -q -tool=memcheck -leak-check=yes to run Valgrind memory check tool (Memcheck) with detailed memory leak detector. This section shows how to profile your applications at ESbox and how to analyse profiling results.

== Installation ==

You do not need to care about Valgrind installation. Once ESbox starts to profile your application with Valgrind, the system checks if necessary packages are properly installed in the environment. If they are not, ESbox installs and configure them. All these steps are performed by Validation Packages wizards, as shown in figure [[#fig:eclipse_memory_profiling_install-valgrind|10.1]].

{| summary="Installing Valgrind at target"
|+ align="BOTTOM" |'''Figure 10.1:''' Installing Valgrind at target
|-
|
[[Image:install-valgrind.png|Image install-valgrind]]
|}

== Profiling your Maemo application with Valgrind ==

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' Valgrind does not run on ARM Linux platform. Therefore, you can only use Valgrind with X86 Maemo SDK rootstraps.
|}

At first, you must create a C/C++, Qt4 or Python Maemo Project and select an X86 Scratchbox target. To run Valgrind, right-click on the application (binary for C/C++ and Qt4 projects or the Python script for Python projects) and select '''Profile As > Local Valgrind Memory Profiler''', figure [[#fig:eclipse_memory_profiling_valgrind-menu|10.2]]. If the tool is not properly installed at the selected target, the system can automatically install it for you, figure [[#fig:eclipse_memory_profiling_install-valgrind|10.1]].

{| summary="Profiling application with Valgrind"
|+ align="BOTTOM" |'''Figure 10.2:''' Profiling application with Valgrind
|-
|
[[Image:valgrind-menu.png|Image valgrind-menu]]
|}

ESbox runs your application on the Maemo SDK X86 target and the result is shown in the Valgrind view, figure [[#fig:eclipse_memory_profiling_valgrind-view|10.3]]. All problems found by Valgrind are shown as a tree: problems as parent nodes and their details as children nodes. Valgrind error messages are explained at chapter [[#Analyzing results]].

{| summary="Valgrind View"
|+ align="BOTTOM" |'''Figure 10.3:''' Valgrind View
|-
|
[[Image:valgrind-view.png|Image valgrind-view]]
|}

{|
|-
| [[Image:dialog-information.png]]
| '''Note:''' If you are planning to run the Valgrind profiler more than once, you will probably need to clear current Valgrind view results before running the current program. For that, you just need to click the '''Delete Current Sample''' button on the Valgrind view toolbar. If you do not, current results are merged with the older ones.
|}

== Analyzing results ==

During Valgrind memory profiling, different problems can be detected, such as:

* Accessing memory locations that must not be accessed, for example, overrunning and underrunning heap blocks, overrunning the top of the stack, and accessing memory after it has been freed.
* Using undefined values, that is, values that have not been initialised, or that have been derived from other undefined values.
* Incorrect freeing of heap memory, such as double-freeing heap blocks, or mismatched use of malloc/new/new[] versus free/delete/delete[].
* Overlapping src and dst pointers in memcpy and related functions.
* Memory leaks.

This section presents a quick summary about some kinds of Valgrind error messages and how to interpret them.

=== Heap block overrun ===

A heap block overrun happens when you try to access (read/write) a block on heap memory that was not properly allocated. For example, an array of 10 integers is created (e.g, array[10]), but you try to access the 11th element, which does not exist. Most C compilers do not warn about this problem, and it is often a potential source of bugs. Most error messages look like the following one, which describes the heap block overrun problem, figure [[#fig:eclipse_memory_profiling_heap-block|10.4]].

{| summary="Heap block overrun"
|+ align="BOTTOM" |'''Figure 10.4:''' Heap block overrun
|-
|
[[Image:valgrind-1.png|Image valgrind-1]]
|}

You must read each error message carefully to understand its information.

* The number between <nowiki>==</nowiki> symbols is the process ID (for example, 7068).
* The parent node (Invalid read of size 4) tells you what kind of error it is. Here, this message says that the program performed an illegal 4-byte read of address 0x406CDC7, which, as far as Memcheck can tell, is not a valid stack address, nor corresponds to any current heap blocks or recently freed heap blocks.
* Details of the problems are shown as children nodes: a stack trace tells you where the problem occurred.
* The code addresses (for example, 0x406CDC7) are usually unimportant, but occasionally crucial for tracking down weird bugs.
* Some error messages have a second component which describes the memory address involved.

=== Memory leaks ===

Another kind of common error is the memory leak, which happens when you do not free previously allocated memory resources, for example arrays. For memory leaks, Valgrind outputs the following messages, figure [[#fig:eclipse_memory_profiling_memory-leak|10.5]].

{| summary="Memory leak"
|+ align="BOTTOM" |'''Figure 10.5:''' Memory leak
|-
|
[[Image:valgrind-2-memory-leak.png|Image valgrind-2-memory-leak]]
|}

Message details tells you where the memory leak is happening. However, it does not tell you why the memory leaks. Among few kinds of leaks, there are two important categories.

* Definitely lost<nowiki>: when the program is really leaking memory. </nowiki>
* Probably lost<nowiki>: when the program is possibly leaking memory. </nowiki>

=== Uninitialised values ===

Memory check also reports uses of uninitialised values, commonly with the message conditional jump or move depends on uninitialised value(s), figure [[#fig:eclipse_memory_profiling_unini-values|10.6]].

{| summary="Uninitialised values"
|+ align="BOTTOM" |'''Figure 10.6:''' Uninitialised values
|-
|
[[Image:valgrind-3-uninitialised-values.png|Image valgrind-3-uninitialised-values]]
|}

An uninitialised-value error is reported when your program uses a value which has not been initialised. In our example, the undefined value was used somewhere inside the <code>_dl_relocate_object</code>.

=== System calls with invalid parameters ===

Another common error is a system call with invalid parameters, figure [[#fig:eclipse_memory_profiling_invalid-parameter|10.7]].

{| summary="Invalid parameters"
|+ align="BOTTOM" |'''Figure 10.7:''' Invalid parameters
|-
|
[[Image:valgrind-4.png|Image valgrind-4]]
|}

This error message shows that there is some uninitialised memory pointed to by buf System call parameter.

There are also other kinds of error messages not listed at this document. More information about them can be found at ''Valgrind Manual'' <ref name=r5>Valgrind Manual. http://valgrind.org/docs/manual/manual.html</ref>.

== References ==
<references />

Documentation/Maemo Eclipse Tutorial/Preface

2010-04-09T09:04:23Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

Documentation/Maemo Documentation Guidelines/Maemo document structure

2010-04-09T08:48:14Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Maemo document structure =

A typical Maemo document has the following structure:

'''Cover page'''
'''Preface'''
'''Table of Contents'''
'''List of Figures'''
'''List of Tables'''
'''Glossary'''
'''Chapter Introduction'''
- introduction to the whole document
'''Chapter AAAAAA'''
'''Section Introduction'''
- introduction to the chapter
- links to example applications
- links to API documents
'''Section BBBBBB'''
'''SubSection bbbbbb'''
'''SubSubSection dddddd'''
'''Paragraph pppppp'''
'''Section CCCCCC'''
'''Section Summary'''
- summary of the chapter
- links for further reading
'''Chapter XXXXXX'''
'''Section Introduction'''
- introduction to the chapter
- links to example applications
- links to API documents
'''Section YYYYYY'''
'''Section Summary'''
- summary of the chapter
- links for further reading
'''Bibliography'''
'''Appendix'''

The document structure given below assumes that each document chapter (except '''Introduction''' chapter for the whole document) is independent from other chapters and can be reused also for other documents, if needed.

; '''Cover page'''
: must have title, publishing date and references to both Nokia Corporation and maemo.org. Cover page will not be included to the table of contents.
; '''Preface'''
: must be based on tempates available as appendixes for this ''Maemo Documentation Guidelines'' document. Base license must be [http://www.gnu.org/copyleft/fdl.html GNU Free Documentation License, version 1.2] and if document includes code examples copyrighted by Nokia they must use MIT-style license. Preface will not be included to the table of contents.
; '''List of Figures and Tables'''
: chapters are optional, for PDF documents only and will not be included to the table of contents.
; '''Glossary'''
: chapter is optional and will not be included to the table of contents.
; '''Introduction'''
: chapter for the whole document and sections for each chapter are mandatory and they do not have Subsections. Introduction section for each chapter must include links to supporting example applications and API documents used in that chapter.
; '''Chapter'''
: always starts from a new page and is independent from other chapters. Chapters can have four different level sections in their internal structure.
; '''Summary'''
: section for each chapter is optional but if used, should give reader links for further reading.
; '''Bibliography'''
: chapter is optional.
; '''Appendix'''
: chapters are optional. Each appendix must start from new page.

----

Documentation/Maemo Documentation Guidelines/B. Maemo FDL-MIT license page

2010-04-09T08:48:14Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= B. Maemo FDL-MIT license page =

Maemo legal page tempate for Maemo documents that uses [http://www.gnu.org/copyleft/fdl.html GNU Free Documentation License, version 1.2] as base license and MIT-style license for code examples copyrighted by Nokia.

= B.1 Preface =

= B.2 Legal notice =

Copyright (c) 2008-2010 Nokia Corporation

Nokia and Maemo are trademarks or registered trademarks of Nokia Corporation. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.

= B.3 Disclaimer =

The information in this document is provided "as is," with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. This document is provided for informational purposes only. Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to implementation of information presented in this document. Nokia Corporation does not warrant or represent that such use will not infringe such rights.

Nokia Corporation retains the right to make changes to this material at any time, without notice.

= B.4 Licenses =

This document is licensed under the [http://www.gnu.org/copyleft/fdl.html GNU Free Documentation License, version 1.2].

Permission is granted to copy, distribute and/or modify documentation under the terms of the GNU Free Documentation License, version 1.2 or any later version published by the Free Software Foundation. Please refer to the copyright notice in each piece of documentation for Invariant Sections, Front-Cover Texts or Back-Cover Texts, if any, as defined in the License.

The code examples copyrighted by Nokia Corporation and included in this document are licensed to you under MIT-style license. License text for that MIT-style license is as follows:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation/Maemo Documentation Guidelines/Glossary

2010-04-09T08:48:13Z

Wikiuser: importing documentation, see Meta:Problems in the LaTeX2HTML2Wiki import process

= Glossary =

; '''API'''
: Application Programming Interface, providing source code level compatibility.
; '''ESbox'''
: Eclipse product implementing integration between Eclipse IDE and Maemo SDK.
; '''GUI'''
: Graphical User Interface.
; '''IP'''
: Internet Protocol is a protocol used for communicating data across a packet-switched internetwork.
; '''LaTeX'''
: is a document markup language and document preparation system for the TeX typesetting program.
; '''Maemo'''
: Software platform for mobile devices developed by Nokia, based on GNU/Linux and GNOME/GTK+ technologies. It includes proprietary components to make it work on the Nokia Maemo compatible device.
; '''maemo.org'''
: Developer community web site maintained by Nokia, main point of reference for open source and third-party developers in general.
; '''Mica'''
: Maemo IDE Common Architecture, Eclipse plugin development framework used by ESbox, PluThon and other Maemo Eclipse products.
; '''OS'''
: Operating System or sometimes Open Source.
; '''PluThon'''
: Eclipse product implementing on-device Python development environment.
; '''Scratchbox'''
: cross-compilation toolkit designed to make embedded Linux application development easier and to cross-compile an entire Linux distribution.
; '''SDK'''
: Software Development Kit.
; '''TeX'''
: is a typesetting system that allows anybody to produce high-quality books using a reasonable amount of effort, and to provide a system that would give the exact same results on all computers.
; '''UI'''
: User Interface.
; '''XML'''
: eXtensible Markup Language.

= Maemo Releases =

; '''Mistral'''
: Maemo 2.0 release for Nokia 770 device. Corresponds to the Nokia Internet Tablet SE 2006 version 2.01.2006.26-8.
; '''Scirocco'''
: Maemo 2.1 release for Nokia 770 device. Includs mainly bugfixes and some other enhancements. Corresponds to Nokia Internet Tablet SE 2006 version 2.2006.39-14.
; '''Gregale'''
: Maemo 2.2 release for Nokia 770 device (bugfixes and enhancements).
; '''Bora'''
: Maemo 3.x releases for Nokia N800 device. Corresponds to Internet Tablet OS releases "1.2006.47-20", "2.2006.51-6" (Maemo 3.0), "3.2007.10-7" (Maemo 3.1) and "4.2007.26-8"+"4.2007.38-2" (Maemo 3.2).
; '''Chinook'''
: Maemo 4.0.x releases for Nokia N800 and N810 devices. Corresponds to Internet Tablet OS releases "1.2007.44-4" (Maemo 4.0) and "2.2007.51-3" (Maemo 4.0.1)
; '''Diablo'''
: Maemo 4.1.x releases for Nokia N800, N810 and N810 WiMAX devices. Corresponds to Internet Tablet OS releases "4.2008.23-14" (Maemo 4.1), "4.2008.36-5" (Maemo 4.1.1) and "5.2008.43-7" (Maemo 4.1.2)
; '''Fremantle'''
: Maemo 5.x releases for N900 device. Corresponds to Maemo 5 OS release "1.2009.42-11" + eMMC content "1.2009.41-1" (Maemo 5) and OS release "2.2009.51-1" + eMMC content "1.2009.41-1" (Maemo 5 Update)
; '''Harmattan'''
: Maemo 6.x releases, corresponds to Maemo 6 OS release "x.2010.xx-x"