Documentation/Maemo Eclipse Tutorial/Setting Up ESbox

(categorize)
(wikify slighty, reformat imges, use <code>)
 
(One intermediate revision not shown)
Line 1: Line 1:
-
= Setting Up ESbox =
+
== Setting up Maemo SDK Virtual Image ==
-
 
+
-
= 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.
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 (<span><font face="monospace"><nowiki>*.vmdk</nowiki></font></span> 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.
+
Recommended virtual machine images are provided by the [[Documentation/Maemo 5 Developer Guide/Development Environment/Maemo SDK Virtual Images|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 (<code>*.vmdk</code> 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 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.
Line 11: Line 9:
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.
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.
+
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 the chapter on [[#Setting Up Shared Folders|setting up shared folders]] for an overview and setup instructions.
-
== Virtual Machine Engines Supported ==
+
=== Virtual Machine Engines Supported ===
ESbox supports VMware, QEMU, and VirtualBox virtualisation technologies for the Maemo SDK Virtual Image.
ESbox supports VMware, QEMU, and VirtualBox virtualisation technologies for the Maemo SDK Virtual Image.
Line 21: Line 19:
* QEMU 0.9.0 and newer may be used for freedom and ease of setup, but is quite slow, even when accelerated.
* 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 ==
+
=== 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.
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.
Line 27: Line 25:
The ESbox wizard '''File &gt; New &gt; Other &gt; Maemo Installers &gt; 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.
The ESbox wizard '''File &gt; New &gt; Other &gt; Maemo Installers &gt; 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.
+
As an alternative 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.
-
{|
+
{{ambox
-
|-
+
|text=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.
-
| [[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 <span><font face="monospace">UseDNS</font></span> 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]].
+
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 <code>UseDNS</code> 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 on [[#Clock synchronization|clock synchronization]].
-
=== Networking Setup ===
+
==== 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''.
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''.
Line 43: Line 39:
''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.
''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 <span><font face="monospace">127.0.0.1:2222</font></span> is used to talk to the VM.
+
''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 <code>127.0.0.1:2222</code> 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.
* 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 <span><font face="monospace">sbrsh</font></span> 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.
+
* SBRSH does not work, since the device communicates with <code>sbrsh</code> 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 <span><font face="monospace">vmnet8</font></span> interface for NAT which has a unique IP address. Unfortunately, this doesn not work reliably.
+
VMware does provide a <code>vmnet8</code> 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.
If you are able to get this working, then you ''can'' use NAT with shared folders and SBRSH.
Line 60: Line 56:
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.
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 ==
+
=== ESbox Build Machine Configuration ===
-
 
+
-
Configuration is under '''Window &gt; Preferences &gt; ESbox &gt; 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]]
+
-
|}
+
 +
Configuration is under '''Window &gt; Preferences &gt; ESbox &gt; 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]].
 +
<div id="fig-virtual_machine_dialog_select_build_machine">
 +
[[Image:dialog-select-build-machine.png|frame|center|alt=unknown|Figure 6.1: Build machine selection reminder]]
 +
</div>
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.
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.
Line 79: Line 68:
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.
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 ==
+
=== Virtual Machine Specific Configuration ===
-
=== VMware 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).
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).
 +
<div id="fig-prefs_exbox_build_machines_vmware">
 +
[[Image:prefs-esbox-build-machines-vmware.png|frame|center|alt=unknown|Figure 6.2: VMware Options]]
 +
</div>
 +
The '''Installation directory''' field should point to either the directory containing <code>vmrun</code>, <code>vmware</code> or <code>vmplayer</code> (in any host) or the <code>VMware Fusion[.app]</code> application or library support directory (in Mac OS X).
-
{| summary="VMware Options"
+
ESbox prefers to use <code>vmrun[.exe]</code> 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 <code>vmplayer[.exe]</code> exists and set the Product Type to '''Player'''.
-
|+ 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 <span><font face="monospace">vmrun</font></span>, <span><font face="monospace">vmware</font></span> or <span><font face="monospace">vmplayer</font></span> (in any host) or the <span><font face="monospace">VMware Fusion[.app]</font></span> application or library support directory (in Mac OS X).
+
-
 
+
-
ESbox prefers to use <span><font face="monospace">vmrun[.exe]</font></span> 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 <span><font face="monospace">vmplayer[.exe]</font></span> 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.
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 ===
+
==== VirtualBox Configuration ====
-
The '''Executable''' should be the <span><font face="monospace">VBoxManage</font></span> 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.
+
The '''Executable''' should be the <code>VBoxManage</code> 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.
 +
<div id="fig-prefs_esbox_build-machines_virtualbox">
 +
[[Image:prefs-esbox-build-machines-virtualbox.png|frame|center|alt=unknown|'''Figure 6.3:''' VirtualBox Options]]
 +
</div>
-
 
+
The '''Command''' pattern spells out how VBoxManage is launched (where <code>$VIRTUALBOX</code> is the "executable" path). This probably needs no changes.
-
{| 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 <span><font face="monospace">$VIRTUALBOX</font></span> 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.
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 ===
+
==== QEMU Configuration ====
-
 
+
-
The '''Installation Directory''' should point to the top-level directory where the QEMU data files (<span><font face="monospace"><nowiki>*.bin</nowiki></font></span>) 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 '''Installation Directory''' should point to the top-level directory where the QEMU data files (<code>*.bin</code>) are located. This may differ from the executable's path.
 +
<div id="fig-prefs_esbox_build_machines_qemu">
 +
[[Image:prefs-esbox-build-machines-qemu.png|frame|center|alt=unknown|'''Figure 6.4:''' QEMU Options]]
 +
</div>
The '''Executable''' is the filename (inside the installation directory) or a full path to the qemu executable.
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 <span><font face="monospace">-kernel-kqemu</font></span>, <span><font face="monospace">-usb</font></span>, 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 '''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 <code>-kernel-kqemu</code>, <code>-usb</code>, 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 '''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 <span><font face="monospace">/dev/hda</font></span>, <span><font face="monospace">/dev/hdb</font></span>, and so on. QEMU supports multiple kinds of disk images (see docs for details). You can use the same maemovmware project VMware <span><font face="monospace"><nowiki>*.vmdk</nowiki></font></span> images here.
+
The '''Disk image(s)''' field is a comma-separated list of full paths to disk images. These images are assigned, in order, to <code>/dev/hda</code>, <code>/dev/hdb</code>, and so on. QEMU supports multiple kinds of disk images (see documentation for details). You can use the same maemovmware project VMware <code>*.vmdk</code> images here.
-
=== Machine Access ===
+
==== 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]].
+
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]].
 +
<div id="fig-virtual_machine_prefs_esbox_build_machines_machine_access">
 +
[[Image:prefs-esbox-build-machines-machine-access.png|frame|center|'''Figure 6.5:''' Machine access]]
 +
</div>
 +
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="Machine access"
+
<div id="fig-virtual_machine_prefs_esbox_build_machines_autoselect_nat">
-
|+ align="BOTTOM" |'''Figure 6.5:''' Machine access
+
[[Image:prefs-esbox-build-machines-autoselect-nat.png|frame|center|alt=unknown|'''Figure 6.6:''' Autoselect NAT]]
-
|-
+
</div>
-
|
+
-
[[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'' (<span><font face="monospace"><nowiki>*.0</nowiki></font></span>) 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]]
+
-
|}
+
 +
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'' (<code>*.0</code>) and warns you to update it, figure [[#fig-virtual_machine_autoselect_bridged|6.7]].
 +
<div id="fig-virtual_machine_autoselect_bridged">
 +
[[Image:prefs-esbox-build-machines-autoselect-bridged.png|frame|center|alt=unknown|'''Figure 6.7:''' Autoselect bridged]]
 +
</div>
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.
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.
Line 189: Line 136:
After closing the dialog, use the '''Apply''' button to accept the changes and launch the virtual machine, if needed.
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]].
+
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]]
+
-
|}
+
-
 
+
 +
<div id="fig-virtual_machine_shut_down_vm">
 +
[[Image:esbox-shut-down-vm.png|frame|center|alt=unknown|'''Figure 6.8:''' Shut down?]]
 +
</div>
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.
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 ===
+
==== 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.
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.
-
{|
+
{{ambox
-
|-
+
|text=For Maemo SDK Virtual Images, the default user is "maemo" and the password is "maemo".
-
| [[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 <span><font face="monospace">/sbin/ifconfig</font></span> to see what address is assigned to <span><font face="monospace">eth0</font></span>.
+
'''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 <code>/sbin/ifconfig</code> to see what address is assigned to <code>eth0</code>.
-
'''Target SSH port''' is the SSH port. This defaults to 2222 for NAT configurations. The default for normal SSH usage is <span><font face="monospace">22</font></span>, but if the Target address is <span><font face="monospace">127.0.0.1</font></span>, this port must be remapped to avoid conflicts with the host.
+
'''Target SSH port''' is the SSH port. This defaults to 2222 for NAT configurations. The default for normal SSH usage is <code>22</code>, but if the Target address is <code>127.0.0.1</code>, 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 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 &gt; NAT &gt; Edit &gt; PortForwarding...''' dialog. Redirect SSH by adding a '''Incoming TCP port''' entry with '''Host Port''' <span><font face="monospace">22</font></span>, '''Virtual Machine Address''' matching the Target Address, and a '''Port''' like <span><font face="monospace">2222</font></span> or <span><font face="monospace">2244</font></span> matching the Target SSH Port setting.
+
For VMware, the port must be configured using the '''Virtual Network Editor &gt; NAT &gt; Edit &gt; PortForwarding...''' dialog. Redirect SSH by adding a '''Incoming TCP port''' entry with '''Host Port''' <code>22</code>, '''Virtual Machine Address''' matching the Target Address, and a '''Port''' like <code>2222</code> or <code>2244</code> matching the Target SSH Port setting.
-
In Windows VMware, if the <span><font face="monospace">VMnet1</font></span> and <span><font face="monospace">VMnet8</font></span> 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 &gt; 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)'''
+
In Windows VMware, if the <code>VMnet1</code> and <code>VMnet8</code> 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 &gt; 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.
If you use both VirtualBox and VMware, be sure to use different SSH ports when enabling port forwarding; otherwise they conflict.
Line 228: Line 166:
For QEMU, this option dictates which port is used, since it is controlled when the machine is launched.
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 <span><font face="monospace">127.0.0.1</font></span><nowiki>! The value depends on the kind of networking you are using with the VM. </nowiki>
+
'''Host address''' is the name of the host as seen from the VM - this is never <code>127.0.0.1</code>! The value depends on the kind of networking you are using with the VM.
For VMware, see the '''VM &gt; Removable Devices &gt; Network Adapter''' menu.
For VMware, see the '''VM &gt; Removable Devices &gt; Network Adapter''' menu.
-
For VirtualBox, see the '''machine &gt; Settings &gt; Network &gt; Adapter''' dialog. If necessary, you can find this by logging into the VM (maemo/maemo) and invoking <span><font face="monospace">/sbin/ifconfig</font></span>.
+
For VirtualBox, see the '''machine &gt; Settings &gt; Network &gt; Adapter''' dialog. If necessary, you can find this by logging into the VM (maemo/maemo) and invoking <code>/sbin/ifconfig</code>.
-
For QEMU, the default is <span><font face="monospace">10.0.2.2</font></span> since the IP is shared with the VM and a private subnet is used to reference the host.
+
For QEMU, the default is <code>10.0.2.2</code> since the IP is shared with the VM and a private subnet is used to reference the host.
-
== Shared Folders ==
+
=== 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.
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.
Line 242: Line 180:
See [http://esbox.garage.maemo.org/2nd_edition/shared_folders.html ESbox Shared Folders] document for an overview and setup instructions.
See [http://esbox.garage.maemo.org/2nd_edition/shared_folders.html ESbox Shared Folders] document for an overview and setup instructions.
-
{|
+
{{ambox
-
|-
+
|text=Currently ESbox only supports Samba (Windows/CIFS) shared folders.
-
| [[Image:dialog-information.png]]
+
}}
-
| '''Note:'''  Currently ESbox only supports Samba (Windows/CIFS) shared folders.
+
-
|}
+
-
{|
+
{{ambox
-
|-
+
|text=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.
-
| [[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 ===
=== Configuration ===
Line 258: Line 192:
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.
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.
 +
<div id="fig-prefs_esbox_build_machines_shared_folders">
 +
[[Image:prefs-esbox-build-machines-shared-folders.png|frame|center|alt=unknown|'''Figure 6.9:''' Shared folders]]
 +
</div>
-
 
+
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 <code>/etc/samba/smb.conf</code>.
-
{| 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 <span><font face="monospace">/etc/samba/smb.conf</font></span>.
+
'''Add Host Share...''' lets you add an entry from the shared folders exposed on the host. These must be manually configured.
'''Add Host Share...''' lets you add an entry from the shared folders exposed on the host. These must be manually configured.
Line 277: Line 204:
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:
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:
-
 
+
<div id="fig-esbox_mount_share">
-
 
+
[[Image:esbox-mount-share.png|frame|center|alt=unknown|'''Figure 6.10:''' SMB Mount]]
-
{| summary="SMB Mount"
+
</div>
-
|+ 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 '''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.
Line 296: Line 216:
To prevent ESbox from trying to mount the share, change the '''Auto mount?''' setting to '''No'''.
To prevent ESbox from trying to mount the share, change the '''Auto mount?''' setting to '''No'''.
-
=== Dynamic shared folder status ===
+
==== 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'''.
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'''.
Line 307: Line 227:
# Edit the entries in the table. The status is updated as you change the fields.
# Edit the entries in the table. The status is updated as you change the fields.
 +
<div id="fig-prefs_esbox_build_machines_shared_folders_2">
 +
[[Image:prefs-esbox-build-machines-shared-folders-2.png|frame|center|alt=unknown|'''Figure 6.11:''' Shared folders]]
 +
</div>
 +
=== ESbox Virtual Machine Behavior ===
-
{| summary="Shared folders"
+
==== Launching ====
-
|+ align="BOTTOM" |'''Figure 6.11:''' Shared folders
+
-
|-
+
-
|
+
-
[[Image:prefs-esbox-build-machines-shared-folders-2.png|Image prefs-esbox-build-machines-shared-folders-2]]
+
-
|}
+
 +
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]].
 +
<div id="fig-virtual_machine_launch_vm">
 +
[[Image:esbox-launch-vm.png|frame|center|alt=unknown|'''Figure 6.12:''' Virtual Machine Needed]]
 +
</div>
-
== ESbox Virtual Machine Behavior ==
+
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]].
-
 
+
-
=== 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]]
+
-
|}
+
-
 
+
 +
<div id="fig-virtual_machine_launch_vm_bad_network">
 +
[[Image:esbox-launch-vm-bad-network.png|frame|center|alt=unknown|'''Figure 6.13:''' Virtual Machine Needed, network problem]]
 +
</div>
# Check the '''Build Machines''' preferences to validate that the '''Machine Access''' settings match.
# Check the '''Build Machines''' preferences to validate that the '''Machine Access''' settings match.
Line 356: Line 255:
Choose '''Launch now''' when you know the machine is not running, and you want ESbox to start it.
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 <span><font face="monospace">dhclient</font></span> or switched between NAT and Bridged modes so that the given address works), or you have fixed the Network Proxy settings in the meantime.
+
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 <code>dhclient</code> 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 <span><font face="monospace"><nowiki>*.vmx</nowiki></font></span> file matters).
+
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 <code>*.vmx</code> file matters).
Choose '''Cancel''', of course, if you do not want to start the virtual machine. This cancels any operation that requested it.
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]].
+
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"
+
<div id="fig-virtual_machine_launching_vm">
-
|+ align="BOTTOM" |'''Figure 6.15:''' Launching Virtual Machine, expanded
+
[[Image:esbox-launching-vm.png|frame|center|alt=unknown'''Figure 6.14:''' Launching Virtual Machine]]
-
|-
+
</div>
-
|
+
-
[[Image:esbox-launching-vm-expanded.png|Image esbox-launching-vm-expanded]]
+
-
|}
+
 +
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]].
 +
<div id="fig-virtual_machine_launching_vm_expanded">
 +
[[Image:esbox-launching-vm-expanded.png|frame|center|alt=unknown|'''Figure 6.15:''' Launching Virtual Machine, expanded]]
 +
</div>
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.
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 ===
+
==== 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]].
+
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]].
 +
<div id="fig-virtual_machine_new_project_vm">
 +
[[Image:esbox-new-project-vm.png|frame|center|alt=unknown|'''Figure 6.16:''' Default project location]]
 +
</div>
 +
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="Default project location"
+
<div id="fig-virtual_machine_new_project_vm_bad">
-
|+ align="BOTTOM" |'''Figure 6.16:''' Default project location
+
[[Image:esbox-new-project-vm-bad.png|frame|center|alt=unknown|'''Figure 6.17:''' Project location, not visible]]
-
|-
+
</div>
-
|
+
-
[[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]]
+
-
|}
+
 +
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]].
 +
<div id="fig-virtual_machine_indexer_settings">
 +
[[Image:esbox-project-indexer-settings.png|frame|center|alt=unknown|'''Figure 6.18:''' Indexer settings]]
 +
</div>
(If you need to change your shared folder setup, or change other things that invalidate these settings, you can use '''Project &gt; Index &gt; Reset Paths and Symbols or Project &gt; Index &gt; Add Missing Paths and Symbols''' to regenerate them from the current mappings.)
(If you need to change your shared folder setup, or change other things that invalidate these settings, you can use '''Project &gt; Index &gt; Reset Paths and Symbols or Project &gt; Index &gt; Add Missing Paths and Symbols''' to regenerate them from the current mappings.)
-
== Clock synchronization ==
+
=== 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.
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.
Line 442: Line 306:
# Log into the virtual machine.
# Log into the virtual machine.
-
# Disable the <span><font face="monospace">/etc/cron.minutely/00resetclock</font></span> script (that is, comment out the <span><font face="monospace">hwclock</font></span> command). This currently runs without appropriate options in respect to the timezone. But note that the clock can drift (without VM engine tools support).
+
# Disable the <code>/etc/cron.minutely/00resetclock</code> script (that is, comment out the <code>hwclock</code> 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 <span><font face="monospace">sudo dpkg-reconfigure tzdata</font></span>.
+
# Reconfigure the time zone to match the one you use in the host, using <code>sudo dpkg-reconfigure tzdata</code>.
-
# Edit <span><font face="monospace">/etc/default/rcS</font></span> and set <span><font face="monospace">UTC=no</font></span>.
+
# Edit <code>/etc/default/rcS</code> and set <code>UTC=no</code>.
-
# Edit <span><font face="monospace">/etc/profile</font></span> and comment out the line: <span><font face="monospace">export TZ=Europe/London</font></span>.
+
# Edit <code>/etc/profile</code> and comment out the line: <code>export TZ=Europe/London</code>.
# Reboot.
# Reboot.
-
# Sync the clock. Run <span><font face="monospace">sudo /sbin/hwclock -localtime -hctosys</font></span>.
+
# Sync the clock. Run <code>sudo /sbin/hwclock -localtime -hctosys</code>.
-
# Verify the time, using <span><font face="monospace">date</font></span>. This should match the current time on the host.
+
# Verify the time, using <code>date</code>. 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.
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 ==
+
=== PC Connectivity Interaction ===
Here are some tips and tricks for using [http://pc-connectivity.garage.maemo.org/ PC Connectivity] with ESbox and virtual machines.
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) ===
+
==== Using USB, Bluetooth, WLAN ad-hoc Networking (static IPs) ====
USB, WLAN Ad-Hoc, and Bluetooth connections use static addresses (<span><font face="monospace">192.168.*.15</font></span>). 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.
USB, WLAN Ad-Hoc, and Bluetooth connections use static addresses (<span><font face="monospace">192.168.*.15</font></span>). 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.
Line 466: Line 330:
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.
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 ===
+
==== 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.
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.
Line 472: Line 336:
Unfortunately, of course, WLAN is very slow and prone to packet loss. It can be more difficult to use when debugging, for example.
Unfortunately, of course, WLAN is very slow and prone to packet loss. It can be more difficult to use when debugging, for example.
-
== Troubleshooting ==
+
=== Troubleshooting ===
'''Cannot access the machine'''
'''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 <span><font face="monospace">sudo dhclient</font></span> 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 <span><font face="monospace">127.0.0.1</font></span> as the Target address in ESbox. For non-NAT cases, the host address is usually <span><font face="monospace">xx.xx.xx.2</font></span> of the target address.
+
* If ESbox cannot guess your network properly, look at the boot screen for the VM or login to the VM (maemo/maemo) and run <code>sudo dhclient</code> 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 <code>127.0.0.1</code> as the Target address in ESbox. For non-NAT cases, the host address is usually <code>xx.xx.xx.2</code> of the target address.
-
* <span><font face="monospace">ping</font></span> 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).
+
* <code>ping</code> 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.
* 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.
Line 491: Line 355:
* The device must be connected to the host (not the VM) in most cases, except for SBRSH (which must use WLAN in most cases).
* 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 <span><font face="monospace">192.168.*</font></span> IP range.
+
* Watch out for firewall software thwarting you. It may block all access to your device. Allow traffic to the <code>192.168.*</code> IP range.
-
* If your LAN uses <span><font face="monospace">192.168.{2,3,4}.*</font></span> 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.
+
* If your LAN uses <code>192.168.{2,3,4}.*</code> 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.
* 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.
* 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.
Line 502: Line 366:
* 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 &gt; Build Automatically''' and Disable '''Window &gt; Preferences &gt; Run/Debug &gt; Build (if required) Before Launching'''
* 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 &gt; Build Automatically''' and Disable '''Window &gt; Preferences &gt; Run/Debug &gt; Build (if required) Before Launching'''
-
= Setting Up Shared Folders =
+
== Setting Up Shared Folders ==
-
== Overview ==
+
=== 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.
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.
Line 515: Line 379:
* Configure: you must tell ESbox what shares you have configured on the '''ESbox &gt; 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]].
* Configure: you must tell ESbox what shares you have configured on the '''ESbox &gt; 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]].
+
See a diagram explaining how this works in an example Windows configuration, figure [[#fig-virtual_machine_esbox_shared_folder_mapping|6.19]].
 +
<div id="fig-virtual_machine_esbox_shared_folder_mapping">
 +
[[Image:esbox-shared-folder-mapping.png|frame|center|alt=unknown|'''Figure 6.19:''' ESbox shared folder mapping]]
 +
</div>
-
 
+
==== Sharing Eclipse Projects ====
-
{| 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.
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 <span><font face="monospace">c:/textbackslash/maemo/shared</font></span>. 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.
+
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 <code>c:/textbackslash/maemo/shared</code>. 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.
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 <span><font face="monospace">/scratchbox</font></span> 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 <span><font face="monospace">/scratchbox/users/&lt;user&gt;/home/&lt;user&gt;/shared</font></span>.
+
Scratchbox 1 uses a sandbox model, whch means only files inside certain directories of <code>/scratchbox</code> 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 <code>/scratchbox/users/&lt;user&gt;/home/&lt;user&gt;/shared</code>.
-
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 <span><font face="monospace">/home/&lt;user&gt;/shared</font></span>.
+
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 <code>/home/&lt;user&gt;/shared</code>.
-
{|
+
{{ambox
-
|-
+
|text=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<br>build-time performance.
-
| [[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<br>build-time performance.
+
-
|}
+
-
=== Sharing Maemo SDK ===
+
==== Sharing Maemo SDK ====
-
CDT's C/C++ indexer parses the sources and headers of C/C++ projects, so you can look up <span><font face="monospace"><nowiki>#includes</nowiki></font></span> 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.
+
CDT's C/C++ indexer parses the sources and headers of C/C++ projects, so you can look up <code>#include</code>s 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.
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.
Line 554: Line 409:
This kind of sharing is not required for normal build, launch, or debug operations.
This kind of sharing is not required for normal build, launch, or debug operations.
-
{|
+
{{ambox
-
|-
+
|text=For sharing from the VM to the host, the network adapter setup in the VM should be Bridged Networking.
-
| [[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 <span><font face="monospace">NET USE</font></span>. Also, in Mac OS X, VMware Fusion does not appear to support user-configured port forwarding.
+
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 <code>NET USE</code>. 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 <span><font face="monospace">compilers</font></span> and <span><font face="monospace">users/.../targets</font></span> directories for Scratchbox 1 (<span><font face="monospace">/scratchbox</font></span> captures both) and the <span><font face="monospace">/home/.../.maemo-sdk</font></span> directory for Scratchbox 2 (the <span><font face="monospace">/home/&lt;user&gt;</font></span> directory is good enough).
+
The virtual machine must export shares so the Maemo rootstraps can be mounted in the host. You want to capture the <code>compilers</code> and <code>users/.../targets</code> directories for Scratchbox 1 (<code>/scratchbox</code> captures both) and the <code>/home/.../.maemo-sdk</code> directory for Scratchbox 2 (the <code>/home/&lt;user&gt;</code> directory is good enough).
The [http://maemovmware.garage.maemo.org/ Maemo SDK Virtual Images] will export these shares by default.
The [http://maemovmware.garage.maemo.org/ Maemo SDK Virtual Images] will export these shares by default.
-
== Default Shared Folders Configuration ==
+
=== Default Shared Folders Configuration ===
ESbox publishes default shares when you configure a new build machine. For Eclipse project sharing, ESbox provides these shares:
ESbox publishes default shares when you configure a new build machine. For Eclipse project sharing, ESbox provides these shares:
* Local share = Yes
* Local share = Yes
-
* Share path = <span><font face="monospace">c:/maemo/shared</font></span> or <span><font face="monospace">/home/&lt;user&gt;/Public</font></span>
+
* Share path = <code>c:/maemo/shared</code> or <code>/home/&lt;user&gt;/Public</code>
-
* Mount path = <span><font face="monospace">/scratchbox/users/maemo/home/maemo/shared</font></span>
+
* Mount path = <code>/scratchbox/users/maemo/home/maemo/shared</code>
and
and
Line 585: Line 438:
* Local share? = No
* Local share? = No
-
* Share path = <span><font face="monospace">/scratchbox</font></span>
+
* Share path = <code>/scratchbox</code>
-
* Mount path = <span><font face="monospace">S:</font></span> or <span><font face="monospace">/Volumes/scratchbox</font></span>
+
* Mount path = <code>S:</code> or <code>/Volumes/scratchbox</code>
and
and
* Local share? = No
* Local share? = No
-
* Share path = <span><font face="monospace">/home/maemo</font></span>
+
* Share path = <code>/home/maemo</code>
-
* Mount path = <span><font face="monospace">T:</font></span> or <span><font face="monospace">/Volumes/maemo</font></span>
+
* Mount path = <code>T:</code> or <code>/Volumes/maemo</code>
Again, change the Mount Path according to your preferences.
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 <span><font face="monospace">~/.maemo-sdk</font></span>. 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.
+
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 <code>~/.maemo-sdk</code>. 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 ==
+
=== How to Make Shares in Windows XP ===
-
Take these steps to share a folder like <span><font face="monospace">c:/maemo/shared</font></span> (or whatever you prefer).
+
Take these steps to share a folder like <code>c:/maemo/shared</code> (or whatever you prefer).
-
=== Enabling sharing services ===
+
==== Enabling sharing services ====
Be sure to enable '''Windows File &amp; Print Sharing'''. You will see it on a fresh system when you first select '''Sharing &amp; Security...''' from a folder's context menu in Windows Explorer. Alternately, visit '''Control Panel &gt; Administrative Tools &gt; Services''' and enable the '''Server''' service.
Be sure to enable '''Windows File &amp; Print Sharing'''. You will see it on a fresh system when you first select '''Sharing &amp; Security...''' from a folder's context menu in Windows Explorer. Alternately, visit '''Control Panel &gt; Administrative Tools &gt; Services''' and enable the '''Server''' service.
-
=== Exporting shares ===
+
==== Exporting shares ====
-
Under Windows Explorer, right click on a folder and select '''Sharing and Security...''', figure [[#fig:shared_folders_xp_share_menu|6.20]].
+
Under Windows Explorer, right click on a folder and select '''Sharing and Security...''', figure [[#fig-shared_folders_xp_share_menu|6.20]].
 +
<div id="fig-shared_folders_xp_share_menu">
 +
[[Image:xp-share-menu.png|frame|center|alt=unknown|'''Figure 6.20:''' Sharing and Security...]]
 +
</div>
 +
You will see a dialog for configuring a share, figure [[#fig-shared_folders_xp_share_dialog|6.21]].
-
{| summary="Sharing and Security..."
+
<div id="fig-shared_folders_xp_share_dialog">
-
|+ align="BOTTOM" |'''Figure 6.20:''' Sharing and Security...
+
[[Image:xp-share-dialog.png|frame|center|alt=unknown|'''Figure 6.21:''' shared Properties]]
-
|-
+
</div>
-
|
+
-
[[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'''.
Check '''Share this folder'''.
Line 640: Line 479:
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.
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]].
+
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]].
 +
<div id="fig-shared_folders_xp_share_permissions">
 +
[[Image:xp-share-permissions.png|frame|center|alt=unknown|'''Figure 6.22:''' Share Permissions]]
 +
</div>
 +
{{ambox
 +
|text=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.}}
-
{| summary="Share Permissions"
+
=== How to Make Shares in Windows Vista ===
-
|+ align="BOTTOM" |'''Figure 6.22:''' Share Permissions
+
-
|-
+
-
|
+
-
[[Image:xp-share-permissions.png|Image xp-share-permissions]]
+
-
|}
+
-
 
+
Take these steps to share a folder like <code>c:/maemo/shared</code> (or whatever you prefer).
-
 
+
-
{|
+
-
|-
+
-
| [[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 <span><font face="monospace">c:/maemo/shared</font></span> (or whatever you prefer).
+
=== Enable file sharing services ===
=== Enable file sharing services ===
-
Under '''Control Panel &gt; Network and Internet &gt; Network and Sharing Center''', the entry '''Sharing and Discovery &gt; File sharing''' should be '''On''', figure [[#fig:shared_folders_vista_share_config|6.23]].
+
Under '''Control Panel &gt; Network and Internet &gt; Network and Sharing Center''', the entry '''Sharing and Discovery &gt; File sharing''' should be '''On''', figure [[#fig-shared_folders_vista_share_config|6.23]].
 +
<div id="fig-shared_folders_vista_share_config">
 +
[[Image:vista-share-config.png|frame|center|alt=unknown|'''Figure 6.23:''' Sharing and Discovery]]
 +
</div>
 +
==== Exporting shares ====
-
{| summary="Sharing and Discovery"
+
Under Windows Explorer, right click on a folder and select '''Share...''', figure [[#fig-shared_folders_vista_menu_share|6.24]].
-
|+ align="BOTTOM" |'''Figure 6.23:''' Sharing and Discovery
+
-
|-
+
-
|
+
-
[[Image:vista-share-config.png|Image vista-share-config]]
+
-
|}
+
 +
<div id="fig-shared_folders_vista_menu_share">
 +
[[Image:vista-menu-share.png|frame|center|alt=unknown|'''Figure 6.24:''' Share...]]
 +
</div>
 +
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]].
-
=== Exporting shares ===
+
<div id="fig-shared_folders_vista_share_permissions">
 +
[[Image:vista-share-permissions.png|frame|center|alt=unknown|'''Figure 6.25:''' Share permissions]]
 +
</div>
-
Under Windows Explorer, right click on a folder and select '''Share...''', figure [[#fig:shared_folders_vista_menu_share|6.24]].
+
{{ambox
 +
|text=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 <code>c:/maemo/shared</code> (or whatever you prefer).
-
{| summary="Share..."
+
==== Enable sharing ====
-
|+ align="BOTTOM" |'''Figure 6.24:''' Share...
+
-
|-
+
-
|
+
-
[[Image:vista-menu-share.png|Image vista-menu-share]]
+
-
|}
+
 +
Under '''Control Panel &gt; Network and Internet &gt; Choose homegroup and sharing options &gt; Change advanced sharing settings...''', the entry '''Turn on file and printer sharing''' should be selected, figure [[#fig-shared_folders_w7_sharing_options|6.26]].
 +
<div id="fig-shared_folders_w7_sharing_options">
 +
[[Image:w7-sharing-options.png|frame|center|alt=unknown|'''Figure 6.26:''' File and printer sharing]]
 +
</div>
-
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]].
+
==== Exporting shares ====
 +
Under Windows Explorer, right click on a folder and select '''Properties''', figure [[#fig-shared_folders_w7_sharing_menu|6.27]].
 +
<div id="fig-shared_folders_w7_sharing_menu">
 +
[[Image:w7-sharing-menu.png|frame|center|alt=unknown|'''Figure 6.27:''' Properties]]
 +
</div>
-
{| summary="Share permissions"
+
Select '''Share''', figure [[#fig-shared_folders_w7_sharing_folder_properties|6.28]].
-
|+ 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 <span><font face="monospace">c:/maemo/shared</font></span> (or whatever you prefer).
+
-
 
+
-
=== Enable sharing ===
+
-
 
+
-
Under '''Control Panel &gt; Network and Internet &gt; Choose homegroup and sharing options &gt; 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]]
+
-
|}
+
-
 
+
 +
<div id="fig-shared_folders_w7_sharing_folder_properties">
 +
[[Image:w7-sharing-folder-properties.png|frame|center|alt=unknown|'''Figure 6.28:''' Share...]]
 +
</div>
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.
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.
-
{|
+
{{ambox
-
|-
+
|text=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.}}
-
| [[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 ==
+
=== How to Make Shares in Mac OS X ===
-
=== Enabling Windows/SMB File Sharing ===
+
==== Enabling Windows/SMB File Sharing ====
Open '''System Preferences &gt; Sharing'''. Click the lock and enter an administrator's credentials to make changes.
Open '''System Preferences &gt; Sharing'''. Click the lock and enter an administrator's credentials to make changes.
Line 775: Line 556:
Enable '''File Sharing'''. Click '''Options....'''
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]].
+
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"
+
<div id="fig-shared_folders_osx_share_smb_enable">
-
|+ align="BOTTOM" |'''Figure 6.29:''' Enable SMB sharing
+
[[Image:osx-share-smb-enable.png|frame|center|alt=unknown|'''Figure 6.29:''' Enable SMB sharing]]
-
|-
+
</div>
-
|
+
-
[[Image:osx-share-smb-enable.png|Image osx-share-smb-enable]]
+
-
|}
+
Click '''Options....'''
Click '''Options....'''
-
{|
+
{{ambox
-
|-
+
|text=In Snow Leopard (10.6 or newer), you have to enable encrypted password support in Samba in the virtual machine. Inside the VM, edit <code>/etc/samba/smb.conf</code> and change the line under the "Authentication" section: <code>encrypt passwords = false</code> to <code>encrypt passwords = true</code>}}
-
| [[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 <span><font face="monospace">/etc/samba/smb.conf</font></span> and change the line under the "Authentication" section: <span><font face="monospace">encrypt passwords = false</font></span> to <span><font face="monospace">encrypt passwords = true</font></span>
+
-
|}
+
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.
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 ===
+
==== Exporting Shares ====
-
 
+
-
Use the default shares for your account (''Public'', which is under <span><font face="monospace">/home/&lt;user&gt;/Public</font></span>), 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]]
+
-
|}
+
 +
Use the default shares for your account (''Public'', which is under <code>/home/&lt;user&gt;/Public</code>), 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]].
 +
<div id="fig-shared_folders_osx_share_prefs">
 +
[[Image:osx-share-prefs.png|frame|center|alt=unknown|'''Figure 6.30:''' File Sharing]]
 +
</div>
The '''Share name''' used in ESbox comes from the label under '''Shared Folders'''.
The '''Share name''' used in ESbox comes from the label under '''Shared Folders'''.
-
== How to Make Shares in Linux ==
+
=== How to Make Shares in Linux ===
-
=== Enabling File Sharing ===
+
==== Enabling File Sharing ====
-
This also uses <span><font face="monospace">Windows-style</font></span> 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 <span><font face="monospace">samba</font></span> package is installed from your distribution's package repository and that <span><font face="monospace">/etc/samba/smb.conf</font></span> file exists.
+
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 <code>samba</code> package is installed from your distribution's package repository and that <code>/etc/samba/smb.conf</code> file exists.
-
=== Exporting Shares (Manual) ===
+
==== Exporting Shares (Manual) ====
'''Method 1'''
'''Method 1'''
-
If you are in the <span><font face="monospace">sambashare</font></span> group, you may define a user share directly. This is done by adding an entry to <span><font face="monospace">/var/lib/samba/usershares</font></span> (or, to the path defined by the <span><font face="monospace">usershare path</font></span> option in <span><font face="monospace">/etc/samba/smb.conf</font></span> file. Try <span><font face="monospace">testparm -s -parameter-name='usershare path'</font></span> to see the setting).
+
If you are in the <code>sambashare</code> group, you may define a user share directly. This is done by adding an entry to <code>/var/lib/samba/usershares</code> (or, to the path defined by the <code>usershare path</code> option in <code>/etc/samba/smb.conf</code> file. Try <code>testparm -s -parameter-name='usershare path'</code> to see the setting).
-
Add a text file to this directory whose name is the Share name (for example, <span><font face="monospace">public</font></span>). Specify its contents like this:
+
Add a text file to this directory whose name is the Share name (for example, <code>public</code>). Specify its contents like this:
-
<nowiki>#VERSION 3
+
<pre>
-
path=/home/localuser/Public
+
#VERSION 3
-
comment=
+
path=/home/localuser/Public
-
usershare_acl=S-1-1-0:F
+
comment=
-
guest_ok=yes
+
usershare_acl=S-1-1-0:F
-
directory mask=755
+
guest_ok=yes
-
create mask=644</nowiki>
+
directory mask=755
 +
create mask=644
 +
</pre>
The share will immediately become available.
The share will immediately become available.
Line 839: Line 607:
If your Samba server is older, you may need to use this format:
If your Samba server is older, you may need to use this format:
-
<nowiki>#VERSION 2
+
<pre>
-
path=/home/localuser/Public
+
#VERSION 2
-
comment=
+
path=/home/localuser/Public
-
usershare_acl=S-1-1-0:F
+
comment=
-
guest_ok=y</nowiki>
+
usershare_acl=S-1-1-0:F
 +
guest_ok=y
 +
</pre>
'''Method 2'''
'''Method 2'''
-
Alternately, you may add the share directly to the Samba configuration. Edit the <span><font face="monospace">/etc/samba/smb.conf</font></span> file as root.
+
Alternately, you may add the share directly to the Samba configuration. Edit the <code>/etc/samba/smb.conf</code> file as root.
Add an entry like the following to the end of the file:
Add an entry like the following to the end of the file:
-
[Public]
+
<pre>
-
writable = yes
+
[Public]
-
public = yes
+
writable = yes
-
browseable = yes
+
public = yes
-
path = /home/localuser/Public
+
browseable = yes
 +
path = /home/localuser/Public
 +
</pre>
-
Substitute appropriate values for <span><font face="monospace">path</font></span> and select a custom share name instead of <span><font face="monospace">Public</font></span> in brackets. The bracketed section name is the <span><font face="monospace">Share name</font></span> used in ESbox.
+
Substitute appropriate values for <code>path</code> and select a custom share name instead of <code>Public</code> in brackets. The bracketed section name is the <code>Share name</code> used in ESbox.
-
Then restart samba with: <span><font face="monospace">$ sudo killall -HUP smbd</font></span>
+
Then restart samba with: <code>sudo killall -HUP smbd</code>
-
=== Exporting Shares (GNOME) ===
+
==== 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]]
+
-
|}
+
 +
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]].
 +
<div id="fig-shared_folders_gnome_share_menu">
 +
[[Image:gnome-share-menu.png|frame|center|alt=unknown|'''Figure 6.31:''' Sharing Options]]
 +
</div>
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'''.
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]].
+
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]]
+
-
|}
+
-
 
+
 +
<div id="fig-shared_folders_gnome_share_dialog">
 +
[[Image:gnome-share-dialog.png|frame|center|alt=unknown|'''Figure 6.32:''' Folder Sharing]]
 +
</div>
Such shares are created as user shares, as described above.
Such shares are created as user shares, as described above.
-
== Troubleshooting ==
+
=== Troubleshooting ===
'''Shared folder configuration problems'''
'''Shared folder configuration problems'''
-
If you cannot mount to shared folders published from Windows, and you get the error <span><font face="monospace">mount error 12 = cannot allocate memory</font></span>, 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.
+
If you cannot mount to shared folders published from Windows, and you get the error <code>mount error 12 = cannot allocate memory</code>, 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 &gt; Administrative Tools &gt; Services &gt; Server''' and restart, or if you have got more time to spare, reboot your system.
+
Edit the key <code>HKEY_ LOCAL_ MACHINE\System\CurrentControlSet \Services\LanmanServer\Parameters\IRPStackSize</code>. Define it as a <code>DWORD</code> 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 &gt; Administrative Tools &gt; Services &gt; 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.
Also see the [http://support.microsoft.com/default.aspx?scid=kb;en-us;177078 Microsoft Knowledge Base] article for more information.
Line 909: Line 667:
If you see warnings like:
If you see warnings like:
-
  make: Warning: File <span><font face="monospace">Makefile</font></span> has modification time <span><font face="monospace">1.1e+07</font></span> in the future <span><font face="monospace">rm -f *.o helloworld</font></span> make: warning: Clock skew detected. Your build may be incomplete.
+
  make: Warning: File <code>Makefile</code> has modification time <code>1.1e+07</code> in the future <code>rm -f *.o helloworld</code> make: warning: Clock skew detected. Your build may be incomplete.
then install the appropriate virtualization tools to ensure the time is synchronized.
then install the appropriate virtualization tools to ensure the time is synchronized.
Line 919: Line 677:
'''Autotools projects fail to build Makefile'''
'''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 <span><font face="monospace">autoconf</font></span> versions and Samba shares.
+
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 <code>autoconf</code> versions and Samba shares.
This may be due to a known file truncation issue that occurs when using <span><font face="monospace">autoconf</font></span> 2.62 or older over Samba shares. Due to trying to rename files before closing them, the <span><font face="monospace">configure</font></span> files will be truncated, preventing Makefiles from being generated. Current Maemo SDKs may still ship these old versions of <span><font face="monospace">autoconf</font></span>.
This may be due to a known file truncation issue that occurs when using <span><font face="monospace">autoconf</font></span> 2.62 or older over Samba shares. Due to trying to rename files before closing them, the <span><font face="monospace">configure</font></span> files will be truncated, preventing Makefiles from being generated. Current Maemo SDKs may still ship these old versions of <span><font face="monospace">autoconf</font></span>.
Line 925: Line 683:
ESbox can repair the <span><font face="monospace">autoconf</font></span> 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 &gt; Preferences &gt; Maemo &gt; Installed Targets''') and select '''Patch autoconf'''. A wizard guides you through the process of repairing the installation.
ESbox can repair the <span><font face="monospace">autoconf</font></span> 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 &gt; Preferences &gt; Maemo &gt; 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 ==
-
== Setting up X Server on Windows ==
+
=== 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.
ESbox has been tested with the Cygwin/X server. Cygwin/X server is recommended since Cygwin is required also for other functionality like SSH.
-
{|
+
{{ambox
-
|-
+
|text=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.
-
| [[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 <span><font face="monospace">setup.exe</font></span> Cygwin installer from the [http://www.cygwin.com/ Cygwin site] and to select the '''X11/xorg-xserver''', '''X11/xinit''' and '''X11/xdpyinfo''' packages.
+
You do not need to install all of Cygwin to use X server. It is sufficient to download the <code>setup.exe</code> 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 ===
=== 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]].
+
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]].
-
{|
+
{{ambox
-
|-
+
|text=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.
-
| [[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.
+
-
|}
+
 +
<div id="fig-x_setup_windows_color_depth_warning">
 +
[[Image:warning_color_depth.png|frame|center|alt=unknown|'''Figure 6.33:''' Colour depth warning]]
 +
</div>
 +
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 &gt; X Server''' command launch parameters, figure [[#fig-x_setup_windows_mouse_pointer_warning|6.34]].
-
{| summary="Colour depth warning"
+
<div id="fig-x_setup_windows_mouse_pointer_warning">
-
|+ align="BOTTOM" |'''Figure 6.33:''' Colour depth warning
+
[[Image:warning_options.png|frame|center|alt=unknown|'''Figure 6.34:''' Mouse pointer warning]]
-
|-
+
</div>
-
|
+
-
[[Image:warning_color_depth.png|Image warning_color_depth]]
+
-
|}
+
 +
You can also see the combined warning if both changes are needed, figure [[#fig-x_setup_windows_combined_warning|6.35]].
 +
<div id="fig-x_setup_windows_combined_warning">
 +
[[Image:warning_color_depth_options.png|frame|center|alt=unknown|'''Figure 6.35:''' Combined warning]]
 +
</div>
-
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 &gt; X Server''' command launch parameters, figure [[#fig:x_setup_windows_mouse_pointer_warning|6.34]].
+
==== How to change colour depth in Windows XP ====
-
 
+
-
 
+
-
 
+
-
{| 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]]
+
-
|}
+
 +
Right-click the desktop, and then click '''Properties''', figure [[#fig-x_setup_windows_xp_desktop|6.36]].
 +
<div id="fig-x_setup_windows_xp_desktop">
 +
[[Image:xp_desktop.png|frame|center|alt=unknown|'''Figure 6.36:''' Windows XP desktop properties]]
 +
</div>
Click the '''Settings''' tab.
Click the '''Settings''' tab.
Line 1,005: Line 731:
Click the drop-down list in the '''Color Quality''' field and select '''Medium (16 bit)'''.
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]].
+
Click '''OK''', figure [[#fig-x_setup_windows_xp_desktop_properties|6.37]].
 +
<div id="fig-x_setup_windows_xp_desktop_properties">
 +
[[Image:xp_display_properties.png|frame|center|alt=unknown|'''Figure 6.37:''' Windows XP Display Properties]]
 +
</div>
 +
==== How to change colour depth in Windows Vista ====
-
{| summary="Windows XP Display Properties"
+
Right-click the desktop, and then click '''Personalize''', figure [[#fig-x_setup_windows_vista_desktop|6.38]].
-
|+ align="BOTTOM" |'''Figure 6.37:''' Windows XP Display Properties
+
-
|-
+
-
|
+
-
[[Image:xp_display_properties.png|Image xp_display_properties]]
+
-
|}
+
 +
<div id="fig-x_setup_windows_vista_desktop">
 +
[[Image:vista_desktop.png|frame|center|alt=unknown|'''Figure 6.38:''' Windows Vista desktop properties]]
 +
</div>
 +
Click the '''Display Settings''', figure [[#fig-x_setup_windows_vista_control_panel|6.39]].
-
=== How to change colour depth in Windows Vista ===
+
<div id="fig-x_setup_windows_vista_control_panel">
-
 
+
[[Image:vista_control_panel.png|frame|center|alt=unknown'''Figure 6.39:''' Windows Vista Personalization]]
-
Right-click the desktop, and then click '''Personalize''', figure [[#fig:x_setup_windows_vista_desktop|6.38]].
+
</div>
-
 
+
-
 
+
-
 
+
-
{| 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 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]].
+
Click '''Ok''', figure [[#fig-x_setup_windows_vista_display_properties|6.40]].
 +
<div id="fig-x_setup_windows_vista_display_properties">
 +
[[Image:vista_display_properties.png|frame|center|alt=unknown|'''Figure 6.40:''' Windows Vista Display Settings]]
 +
</div>
 +
==== How to change the display colour depth in Windows 7 ====
-
{| summary="Windows Vista Display Settings"
+
Open the Control panel ('''Start &gt; Control Panel'''), figure [[#fig-x_setup_windows_7_control_panel_menu|6.41]].
-
|+ align="BOTTOM" |'''Figure 6.40:''' Windows Vista Display Settings
+
-
|-
+
-
|
+
-
[[Image:vista_display_properties.png|Image vista_display_properties]]
+
-
|}
+
 +
<div id="fig-x_setup_windows_7_control_panel_menu">
 +
[[Image:7_control_panel_menu.png|frame|center|alt=unknown|'''Figure 6.41:''' Windows 7 Start menu]]
 +
</div>
 +
Click '''Adjust screen resolution''' under '''Appearance and Personalization''', figure [[#fig-x_setup_windows_7_appearance_personalization|6.42]].
-
=== How to change the display colour depth in Windows 7 ===
+
<div id="fig-x_setup_windows_7_appearance_personalization">
 +
[[Image:7_appearance_personalization.png|frame|center|alt=unknown|'''Figure 6.42:''' Windows 7 Control Panel]]
 +
</div>
-
Open the Control panel ('''Start &gt; Control Panel'''), figure [[#fig:x_setup_windows_7_control_panel_menu|6.41]].
+
Click '''Advanced settings''', figure [[#fig-x_setup_windows_7_screen_resolution|6.43]].
 +
<div id="fig-x_setup_windows_7_screen_resolution">
 +
[[Image:7_screen_resolution.png|frame|center|alt=unknown|'''Figure 6.43:''' Windows 7 Screen Resolution]]
 +
</div>
 +
Click the '''Monitor''' tab, figure [[#fig-x_setup_windows_7_monitor_tab|6.44]].
-
{| summary="Windows 7 Start menu"
+
<div id="fig-x_setup_windows_7_monitor_tab">
-
|+ align="BOTTOM" |'''Figure 6.41:''' Windows 7 Start menu
+
[[Image:7_monitor_tab.png|frame|center|alt=unknown'''Figure 6.44:''' Windows 7 Monitor tab]]
-
|-
+
</div>
-
|
+
-
[[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'''.
Under '''Colors''', select '''High Color (16 bit)''', and then click '''OK'''.
-
== Setting up X Server on Mac OS X ==
+
=== Setting up X Server on Mac OS X ===
-
=== Installing the server ===
+
==== 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].
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 ===
+
==== 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 &gt; Display field'''.
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 &gt; Display field'''.
-
{|
+
{{ambox
-
|-
+
|text=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.
-
| [[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]]
+
-
|}
+
 +
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]].
 +
<div id="fig-x_setup_mac_shm_warning">
 +
[[Image:shm_warning.png|frame|center|alt=unknown|'''Figure 6.45:''' MIT-SHM extension warning]]
 +
</div>
Click '''Yes''' to warning above to disable MIT-SHM extension in the command launch pattern in the '''ESbox &gt; X Server''' preference page and restart the server.
Click '''Yes''' to warning above to disable MIT-SHM extension in the command launch pattern in the '''ESbox &gt; X Server''' preference page and restart the server.

Latest revision as of 14:11, 15 September 2010

Contents

[edit] 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 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 (*.vmdk 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 the chapter on setting up shared folders for an overview and setup instructions.

[edit] 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.

[edit] 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 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 alternative 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:Ambox_notice.png
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 on clock synchronization.

[edit] 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.

[edit] 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 6.1.

File:Dialog-select-build-machine.png
Figure 6.1: Build machine selection reminder

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.

[edit] Virtual Machine Specific Configuration

[edit] 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).

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.

[edit] 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.

File:Prefs-esbox-build-machines-virtualbox.png
Figure 6.3: VirtualBox Options

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 Maemo SDK Virtual Image documentation for details.

[edit] QEMU Configuration

The Installation Directory should point to the top-level directory where the QEMU data files (*.bin) are located. This may differ from the executable's path.

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 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 documentation for details). You can use the same maemovmware project VMware *.vmdk images here.

[edit] 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 6.5.

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

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 (*.0) and warns you to update it, figure 6.7.

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

File:Esbox-shut-down-vm.png
Figure 6.8: Shut down?

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.

[edit] 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:Ambox_notice.png
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 Maemo SDK Virtual Image VirtualBox configuration document, the 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! The value depends on the kind of networking you are using with the VM.

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.

[edit] 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 ESbox Shared Folders document for an overview and setup instructions.

Image:Ambox_notice.png
Currently ESbox only supports Samba (Windows/CIFS) shared folders.
Image:Ambox_notice.png
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.

[edit] 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 ESbox Shared Folders document for details.

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:

File:Esbox-mount-share.png
Figure 6.10: SMB Mount

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.

[edit] 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:

  1. Be sure the Machine Access > Target Address and Host Address fields are valid.
  2. Be sure the VM has been launched (using Launch Machine or a previous Validate Machine invocation).
  3. Enable the checkbox.
  4. Edit the entries in the table. The status is updated as you change the fields.

[edit] ESbox Virtual Machine Behavior

[edit] 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 6.12.

File:Esbox-launch-vm.png
Figure 6.12: Virtual Machine Needed

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

File:Esbox-launch-vm-bad-network.png
Figure 6.13: Virtual Machine Needed, network problem
  1. Check the Build Machines preferences to validate that the Machine Access settings match.
  2. 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.
  3. Check the 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 *.vmx 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 6.14.

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

File:Esbox-launching-vm-expanded.png
Figure 6.15: Launching Virtual Machine, 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.

[edit] 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 6.16.

File:Esbox-new-project-vm.png
Figure 6.16: Default project location

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

File:Esbox-new-project-vm-bad.png
Figure 6.17: Project location, not visible

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

File:Esbox-project-indexer-settings.png
Figure 6.18: 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.)

[edit] 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:

  1. Log into the virtual machine.
  2. 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).
  3. Reconfigure the time zone to match the one you use in the host, using sudo dpkg-reconfigure tzdata.
  4. Edit /etc/default/rcS and set UTC=no.
  5. Edit /etc/profile and comment out the line: export TZ=Europe/London.
  6. Reboot.
  7. Sync the clock. Run sudo /sbin/hwclock -localtime -hctosys.
  8. 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.

[edit] PC Connectivity Interaction

Here are some tips and tricks for using PC Connectivity with ESbox and virtual machines.

[edit] 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.

[edit] 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.

[edit] 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

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

[edit] Setting Up Shared Folders

[edit] Overview

Shared folders are needed when you run ESbox with a virtual machine outside the Debian Linux/x86 host. See 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 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 ESbox Using Virtual Imges documents and chapter #Shared Folders.

See a diagram explaining how this works in an example Windows configuration, figure 6.19.

File:Esbox-shared-folder-mapping.png
Figure 6.19: ESbox shared folder mapping

[edit] 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:Ambox_notice.png
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.

[edit] Sharing Maemo SDK

CDT's C/C++ indexer parses the sources and headers of C/C++ projects, so you can look up #includes 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:Ambox_notice.png
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 Maemo SDK Virtual Images will export these shares by default.

[edit] 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.

[edit] How to Make Shares in Windows XP

Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).

[edit] 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.

[edit] Exporting shares

Under Windows Explorer, right click on a folder and select Sharing and Security..., figure 6.20.

File:Xp-share-menu.png
Figure 6.20: Sharing and Security...

You will see a dialog for configuring a share, figure 6.21.

File:Xp-share-dialog.png
Figure 6.21: shared Properties

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

File:Xp-share-permissions.png
Figure 6.22: Share Permissions
Image:Ambox_notice.png
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.

[edit] How to Make Shares in Windows Vista

Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).

[edit] 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 6.23.

File:Vista-share-config.png
Figure 6.23: Sharing and Discovery

[edit] Exporting shares

Under Windows Explorer, right click on a folder and select Share..., figure 6.24.

File:Vista-menu-share.png
Figure 6.24: 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 6.25.

File:Vista-share-permissions.png
Figure 6.25: Share permissions
Image:Ambox_notice.png
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.

[edit] How to Make Shares in Windows 7

Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).

[edit] 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 6.26.

File:W7-sharing-options.png
Figure 6.26: File and printer sharing

[edit] Exporting shares

Under Windows Explorer, right click on a folder and select Properties, figure 6.27.

File:W7-sharing-menu.png
Figure 6.27: Properties

Select Share, figure 6.28.

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:Ambox_notice.png
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.

[edit] How to Make Shares in Mac OS X

[edit] 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 6.29.

File:Osx-share-smb-enable.png
Figure 6.29: Enable SMB sharing

Click Options....

Image:Ambox_notice.png
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.

[edit] 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 6.30.

File:Osx-share-prefs.png
Figure 6.30: File Sharing

The Share name used in ESbox comes from the label under Shared Folders.

[edit] How to Make Shares in Linux

[edit] 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.

[edit] 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:

#VERSION 3
path=/home/localuser/Public
comment=
usershare_acl=S-1-1-0:F
guest_ok=yes
directory mask=755
create mask=644

The share will immediately become available.

If your Samba server is older, you may need to use this format:

#VERSION 2
path=/home/localuser/Public
comment=
usershare_acl=S-1-1-0:F
guest_ok=y

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

[edit] 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 6.31.

File:Gnome-share-menu.png
Figure 6.31: Sharing Options

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

File:Gnome-share-dialog.png
Figure 6.32: Folder Sharing

Such shares are created as user shares, as described above.

[edit] 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 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: make: *** No rule to make target 'all'. Stop. 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.

[edit] Setting up X Server

[edit] 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:Ambox_notice.png
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 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 Cygwin site and to select the X11/xorg-xserver, X11/xinit and X11/xdpyinfo packages.

[edit] 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 6.33.

Image:Ambox_notice.png
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.
File:Warning color depth.png
Figure 6.33: Colour depth warning

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

File:Warning options.png
Figure 6.34: Mouse pointer warning

You can also see the combined warning if both changes are needed, figure 6.35.

File:Warning color depth options.png
Figure 6.35: Combined warning

[edit] How to change colour depth in Windows XP

Right-click the desktop, and then click Properties, figure 6.36.

File:Xp desktop.png
Figure 6.36: Windows XP desktop properties

Click the Settings tab.

Click the drop-down list in the Color Quality field and select Medium (16 bit).

Click OK, figure 6.37.

File:Xp display properties.png
Figure 6.37: Windows XP Display Properties

[edit] How to change colour depth in Windows Vista

Right-click the desktop, and then click Personalize, figure 6.38.

File:Vista desktop.png
Figure 6.38: Windows Vista desktop properties

Click the Display Settings, figure 6.39.

Click the drop-down list in the Colors field and select Medium (16 bit).

Click Ok, figure 6.40.

File:Vista display properties.png
Figure 6.40: Windows Vista Display Settings

[edit] How to change the display colour depth in Windows 7

Open the Control panel (Start > Control Panel), figure 6.41.

File:7 control panel menu.png
Figure 6.41: Windows 7 Start menu

Click Adjust screen resolution under Appearance and Personalization, figure 6.42.

File:7 appearance personalization.png
Figure 6.42: Windows 7 Control Panel

Click Advanced settings, figure 6.43.

File:7 screen resolution.png
Figure 6.43: Windows 7 Screen Resolution

Click the Monitor tab, figure 6.44.

Under Colors, select High Color (16 bit), and then click OK.

[edit] Setting up X Server on Mac OS X

[edit] Installing the server

The Xephyr server is recommended since it tracks the newest X server extensions used by Fremantle. Find this in the Xquartz project.

[edit] 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:Ambox_notice.png
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 6.45.

File:Shm warning.png
Figure 6.45: MIT-SHM extension 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.