Documentation/Maemo Eclipse Tutorial/Setting Up ESbox
Contents
|
Setting Up ESbox
Setting up Maemo SDK Virtual Image
The Maemo SDK, Scratchbox, and rootstraps run only on Linux/x86. If you want to use ESbox in Windows or MacOS X - or even Linux/x86-64 - then you can do this by hooking up ESbox with an appropriately configured virtual machine.
Recommended virtual machine images are provided by the 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 chapter #Setting Up Shared Folders for an overview and setup instructions.
Virtual Machine Engines Supported
ESbox supports VMware, QEMU, and VirtualBox virtualisation technologies for the Maemo SDK Virtual Image.
- VMware Workstation/Server 6.x (or Player 2.5.x and 3.x) is supported and recommended for speed. We have detected some problems using VMware Player 3.0. It seems that SSH dropouts are common in this version. VMware Player 2.5.x seems to work fine.
- VirtualBox 2.1 or newer is supported and recommended for freedom and consistency of behavior across operating systems.
- QEMU 0.9.0 and newer may be used for freedom and ease of setup, but is quite slow, even when accelerated.
Virtual Machine Images
ESbox runs best with a preconfigured Ubuntu Server-based Maemo SDK Virtual Image, which has a minimal footprint. This "Server" image is configured to provide the best interaction with ESbox. The "Server" image may be used with any of the virtualisation engines above.
The ESbox wizard File > New > Other > Maemo Installers > Maemo SDK Virtual Image lets you fetch and install the recommended images maintained by the 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.
| File:Dialog-information.png | Note: You should not use the "Desktop" image with native ESbox installation (configuration where Eclipse IDE has been installed to the host PC instead of Maemo SDK Virtual Image) as the "Desktop" image already includes ESbox pre-installed. |
If you want to use your own virtual image instead of Maemo SDK Virtual Images, ensure it has SSH and Samba support. For SSH, the UseDNS flag should be switched off, and to support Samba, you may need an often-running cron job to resynchronize the clock with the host, to avoid timestamp drift issues when building, see the chapter #Clock synchronization.
Networking Setup
A very important aspect of the ESbox and VM configuration is the networking mode. Modern VM engines usually allow three modes for how the VM virtualizes network access: host, NAT, and bridged.
Host is useless for ESbox, since it implies that the outside world cannot see the VM, and ESbox would be on the outside. Don't use this mode.
NAT is a mode where the VM shares the IP address of the host. This is useful in a lot of cases with ESbox, but it is not appropriate in the default configuration recommended by ESbox, where the address 127.0.0.1:2222 is used to talk to the VM.
- Shared folders cannot be exposed from the VM to the host, which makes it difficult to use C/C++ indexing and searches with the Maemo SDK. This is because we cannot use port forwarding to remap the Windows CIFS ports to distinguish the hosts from the VMs.
- SBRSH does not work, since the device communicates with sbrsh running under Scratchbox, but the IP address is the same as the host, which does not run the server. Complex port forwarding could make this work too, but it is not worth the effort.
VMware does provide a vmnet8 interface for NAT which has a unique IP address. Unfortunately, this doesn not work reliably.
If you are able to get this working, then you can use NAT with shared folders and SBRSH.
Since it is not an easy setup, we don not recommend using this mode, unless you know what you are doing, or you have no other choice (for example, QEMU).
Bridged is a mode where the virtual machine has its own IP address on the LAN. To all intents and purposes it appears to be a distinct machine on the network. This gives it enough flexibility to support the shared folder mappings and SBRSH usage mentioned above.
On the other hand, Bridged mode introduces the inconvenience that the DHCP-assigned address of the VM may change between restarts of the machine. This means you need to manually correct the address (for example, in the Machine Access pane described below). But ESbox provides helpful dialogs reminding you that you may need to update this address and I myself have used it successfully for months.
So, Bridged mode is the best of the three options and we recommend this one. This is the default for the "server image" provided by the maemovmware project. If you want to change to NAT, you need to reconfigure the networking devices for the given image in the VM engine of choice. See your documentation for details.
ESbox Build Machine Configuration
Configuration is under Window > Preferences > ESbox > Build Machines. If you navigate here before configuring anything, or try to create a project and launch first, you will get a message directing you to the page, figure 6.1.
You need to select a virtual machine engine (or Manual configuration) and adjust the settings on all the pages accordingly. Each engine has product-specific configuration.
Any selected build machine has a unique configuration in Machine Access (the user name, password, target/host addresses and ports) and Shared Folders (the shares providing a mapping between the host and target filesystems) tabs. All machines except for Manually Launched have a VM-specific configuration tab as well.
Virtual Machine Specific Configuration
VMware Configuration
The Product type field lets you select along multiple available VMware engines if you have more than one installed. This is mostly useful if you have installed VMware Workstation or Server, but want to use VMware Player (since they exist in the same directory).
The Installation directory field should point to either the directory containing vmrun, vmware or vmplayer (in any host) or the VMware Fusion[.app] application or library support directory (in Mac OS X).
ESbox prefers to use vmrun[.exe] for all operations as a command-line controller for virtual machine operations (enumerating, launching, and stopping virtual machines). ESbox is flexible and will look up the directory tree from the specified location to locate the expected executable. If you only have VMware Player, or only want to use player, point to the directory where vmplayer[.exe] exists and set the Product Type to Player.
The VMX path is the primary file describing the virtual machine (which disk images it uses, what its networking configuration is, and so on). You can edit its settings in a running VMware client.
VirtualBox Configuration
The Executable should be the VBoxManage program, which is the command line controller for VirtualBox. ESbox uses this to detect whether machines are running, which machines are available (under the Virtual Machine dropdown), and to launch and stop machines.
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.
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 docs for details). You can use the same maemovmware project VMware *.vmdk images here.
Machine Access
Some fields in the Machine Access settings should be preconfigured to match the images from the Maemo SDK Virtual Image project, but you need to edit the address and port settings depending on your networking configuration, figure 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.
If the machine and disk are the same as the running machine, and you are just synchronizing network settings, you may be able to leave it running. In any event, the supported VM engines themselves are not able to write to the same disk images opened by another engine.
More Details
The Machine Access tab allows you to configure the networking and authentication with the VM. User is the account which acts as the agent for all operations with the VM. It should be the same user who owns the Scratchbox installation(s). Password is the password for the user account.
| File:Dialog-information.png | Note: For Maemo SDK Virtual Images, the default user is "maemo" and the password is "maemo". |
Target address is the address used to access the VM. This may be an IP address or a name. If the Autoselect Settings button cannot figure it out, you need to discover this experimentally, by watching the boot-time messages, or logging in and using /sbin/ifconfig to see what address is assigned to eth0.
Target SSH port is the SSH port. This defaults to 2222 for NAT configurations. The default for normal SSH usage is 22, but if the Target address is 127.0.0.1, this port must be remapped to avoid conflicts with the host.
For VirtualBox, this port must match the configuration established for a machine via VBoxManage before the machine is launched. See more instructions from the 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.
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.
| File:Dialog-information.png | Note: Currently ESbox only supports Samba (Windows/CIFS) shared folders. |
| File:Dialog-information.png | Note: To expose shares from the VM to the host, you must use Bridged networking in the VM. Otherwise you need to understand a lot about port forwarding. |
Configuration
The default shares are suggestions for the most common setup, so that projects can be built for multiple Scratchbox targets, and so indexing can work. See 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:
The username is, by default, the same as the main user account on the given machine, but you may change it if needed, depending on the share's permissions.
The workgroup/domain may not be required unless you are logged into a Windows domain.
The password is remembered for future launches of the mount during the current Eclipse session, but it is discarded if the mount fails.
To prevent ESbox from trying to mount the share, change the Auto mount? setting to No.
Dynamic shared folder status
The Check folder status while editing checkbox dynamically validates the shared folders against a running VM, to assist with some issues that may be tedious to debug by using Validate Machines.
To use this:
- Be sure the Machine Access > Target Address and Host Address fields are valid.
- Be sure the VM has been launched (using Launch Machine or a previous Validate Machine invocation).
- Enable the checkbox.
- Edit the entries in the table. The status is updated as you change the fields.
ESbox Virtual Machine Behavior
Launching
Usually, only an explicit user action (like starting a wizard, validating the VM, or viewing ESbox or Maemo preference panels) requires the VM to be running. ESbox connects to a running virtual machine that responds to the configured machine engine, target address, and SSH port in the Machine Access settings. If the specified engine or configured image is not running, then ESbox prompts you to launch the configured machine, figure 6.12.
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.
- Check the Build Machines preferences to validate that the Machine Access settings match.
- Check Network Connections preferences in case you are behind a proxy but the VM is not. ESbox uses the proxy settings for all network operations.
- Check the 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.
Closing this dialog does not cancel any operation. It is only informative, to help you look for common problems and solutions while configuring the machine.
Shared folder mappings
Once you have configured mapping that expose the project to the VM, ESbox automatically selects a project location inside a shared folder for you, when you create or import a project, figure 6.16.
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.
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.
(If you need to change your shared folder setup, or change other things that invalidate these settings, you can use Project > Index > Reset Paths and Symbols or Project > Index > Add Missing Paths and Symbols to regenerate them from the current mappings.)
Clock synchronization
When you perform C/C++ builds in ESbox, it is essential that the clock settings in the host and the virtual machine match, since they share a Samba filesystem whose timestamps determine whether any work needs to be done. If they mismatch, then either your Make output is littered with "timestamp drift" messages or your programs are not rebuilt as expected.
Unfortunately, the virtual machine engine and configuration influence the clock in different ways. (For example, in VMware, the clock may act differently depending on whether the VMware Tools are installed.) You will need to manually configure your system and experiment to make things work.
One approach is:
- Log into the virtual machine.
- Disable the /etc/cron.minutely/00resetclock script (that is, comment out the hwclock command). This currently runs without appropriate options in respect to the timezone. But note that the clock can drift (without VM engine tools support).
- Reconfigure the time zone to match the one you use in the host, using sudo dpkg-reconfigure tzdata.
- Edit /etc/default/rcS and set UTC=no.
- Edit /etc/profile and comment out the line: export TZ=Europe/London.
- Reboot.
- Sync the clock. Run sudo /sbin/hwclock -localtime -hctosys.
- Verify the time, using date. This should match the current time on the host.
Now, you can create files in a shared folder and validate their timestamps to match those on the host. In my experiments with VMware Fusion on OS X, unfortunately, the timstamps were off by as much as 5 seconds. So this led to several annoying messages if I built several times in a row, but it is manageable.
PC Connectivity Interaction
Here are some tips and tricks for using PC Connectivity with ESbox and virtual machines.
Using USB, Bluetooth, WLAN ad-hoc Networking (static IPs)
USB, WLAN Ad-Hoc, and Bluetooth connections use static addresses (192.168.*.15). The default network routing configurations for the host mean that they are only able to directly communicate back and forth with one "machine" at a time. In most cases, you should connect the machine to the host, rather than the virtual machine. Eclipse manages most of the SSH traffic with the device, so the host needs to be able to see the device at its static address. The host cannot see network traffic inside the VM.
Conversely, from the device point of view, the device can only see the machine it is connected to. For cases where the device needs to open a socket from the host, the device must be able to see the host at the host address (192.168.*.14). This includes Python debugging and SBRSH.
Note: if you are using NAT networking with the virtual machine, the VM is also able to see the device at the static address. This is the best of both worlds.
Note: When using SBRSH, you most likely need to use WLAN instead of a static IP configuration. The device must be visible on the network inside the virtual machine and the host machine, since SBRSH runs under Scratchbox, and the device needs to mount filesystems from the VM and host.
Using WLAN Networking
WLAN networking is the most flexible option, as long as your virtual machine is configured for Bridged networking, where it has its own DHCP-acquired address. In this model, the host, the VM, and the device are all peers on the LAN. Thus, the device is visible to the host and the VM, and the device can see the host and the VM.
Unfortunately, of course, WLAN is very slow and prone to packet loss. It can be more difficult to use when debugging, for example.
Troubleshooting
Cannot access the machine
- If ESbox cannot guess your network properly, look at the boot screen for the VM or login to the VM (maemo/maemo) and run sudo dhclient to validate the assigned IP address for the VM, if you are not getting a connection. Only in the case of NAT should you enter 127.0.0.1 as the Target address in ESbox. For non-NAT cases, the host address is usually xx.xx.xx.2 of the target address.
- ping is a very useful feature. In case of connection problems, cross-check the address displayed, for example, in a launch configuration or in the RSE connection, and verify that you can see if they are from your host or your VM (depending on context).
- If you are having trouble accessing port forwarding over SSH, note that VMware's virtual network port mappings apply even when it is not hosting a running VM. In such cases, select different target ports for other VM engines.
Scratchbox not found
- If you have first set up a machine and have had some difficulties with configuring it, you can set ESbox up to make it detect Scratchbox and targets. Go to Window > Preferences > Maemo > Installed Targets and hit Refresh.
Shared folder issues
- See ESbox Shared Folders document, troubleshooting chapter for more information.
Device access issues
- The device must be connected to the host (not the VM) in most cases, except for SBRSH (which must use WLAN in most cases).
- Watch out for firewall software thwarting you. It may block all access to your device. Allow traffic to the 192.168.* IP range.
- If your LAN uses 192.168.{2,3,4}.* for its own DHCP server, and you want to use the static USB, Bluetooth, or WLAN ad-hoc connections, you need to have separate subnets. Reconfigure these static addresses in the PC-Connectivity Manager and in your host configuration.
- Avoid host-only networking configurations in your VM. Otherwise you are unable to contact the device or the Internet.
- SBRSH needs to communicate in three ways: between the host (running Eclipse), the VM (hosting Scratchbox and running the sbrsh client), and the device (running the sbrsh daemon). In most cases, you must use WLAN for this to work, unless you know how to manually configure routing tables to do this over USB or Bluetooth or the ad-hoc WLAN connection.
Virtual machine launching when not using ESbox
- Eclipse sometimes triggers builds for all projects in the workspace, which may be a problem if you are using other products in your installation and do not want to be prompted to launch the VM.
- The easiest solution is to switch the Build Machine to None. (With this setting, you cannot use most ESbox actions, since no installed targets except for Remote Connections are recognized.) An alternative is to use the Manually Launched Machine setting. If you use ESbox commands, it fails to connect immediately if no machine responds to the address.
- Alternately, a configured build machine can live alongside other products if you avoid allowing Eclipse to build ESbox projects: Close ESbox projects or Disable Project > Build Automatically and Disable Window > Preferences > Run/Debug > Build (if required) Before Launching
Setting Up Shared Folders
Overview
Shared folders are needed when you run ESbox with a virtual machine outside the Debian Linux/x86 host. See 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.
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.
| File:Dialog-information.png | Note: This choice exposes occasional problems when Unix filesystem semantics are not fully emulated over Samba shares, such as when softlinks are created by build scripts, and building is a little slower than with a native filesystem. But we chose to optimize for ease of Eclipse integration and speed of IDE/editor/debugger-time activity over build-time performance. |
Sharing Maemo SDK
CDT's C/C++ indexer parses the sources and headers of C/C++ projects, so you can look up #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.
| File:Dialog-information.png | Note: For sharing from the VM to the host, the network adapter setup in the VM should be Bridged Networking. |
NAT networking requires port forwarding over the CIFS port 445 to avoid conflicting with the SMB/CIFS server in host PC, but Windows at least does not easily allow you to specify an alternate CIFS port with programs like NET USE. Also, in Mac OS X, VMware Fusion does not appear to support user-configured port forwarding.
The virtual machine must export shares so the Maemo rootstraps can be mounted in the host. You want to capture the compilers and users/.../targets directories for Scratchbox 1 (/scratchbox captures both) and the /home/.../.maemo-sdk directory for Scratchbox 2 (the /home/<user> directory is good enough).
The Maemo SDK Virtual Images will export these shares by default.
Default Shared Folders Configuration
ESbox publishes default shares when you configure a new build machine. For Eclipse project sharing, ESbox provides these shares:
- Local share = Yes
- Share path = c:/maemo/shared or /home/<user>/Public
- Mount path = /scratchbox/users/maemo/home/maemo/shared
and
- Local share = Yes
- Share path = c:/ maemo/shared or /home/<user>/Public
- Mount path = /home/maemo/shared
Feel free to change the Share Path to whatever you have on your system. The Mount Paths, though, have been selected specially. They point into the user's home on the VM so that Scratchbox 1 and Scratchbox 2 can see the projects in the same Scratchbox-relative directory at build time. Additionally, they point to a location that map the same no matter which target you are building.
For Maemo SDK sharing, ESbox provides these shares:
- Local share? = No
- Share path = /scratchbox
- Mount path = S: or /Volumes/scratchbox
and
- Local share? = No
- Share path = /home/maemo
- Mount path = T: or /Volumes/maemo
Again, change the Mount Path according to your preferences.
These shares allow access to enough of the SDK to allow full C/C++ indexing. The home directory is exposed mainly because Scratchbox 2 places SDKs under ~/.maemo-sdk. However, we suggest the whole home directory, which may be useful, if you want to move files back and forth between the host and VM.
How to Make Shares in Windows XP
Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).
Enabling sharing services
Be sure to enable Windows File & Print Sharing. You will see it on a fresh system when you first select Sharing & Security... from a folder's context menu in Windows Explorer. Alternately, visit Control Panel > Administrative Tools > Services and enable the Server service.
Exporting shares
Under Windows Explorer, right click on a folder and select Sharing and Security..., figure 6.20.
You will see a dialog for configuring a share, figure 6.21.
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:Dialog-information.png | Note: Export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox does not propose adding mappings for exported drives. |
How to Make Shares in Windows Vista
Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).
Enable file sharing services
Under Control Panel > Network and Internet > Network and Sharing Center, the entry Sharing and Discovery > File sharing should be On, figure 6.23.
Exporting shares
Under Windows Explorer, right click on a folder and select Share..., figure 6.24.
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:Dialog-information.png | Note: Export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox does not propose adding mappings for exported drives. |
How to Make Shares in Windows 7
Take these steps to share a folder like c:/maemo/shared (or whatever you prefer).
Enable sharing
Under Control Panel > Network and Internet > Choose homegroup and sharing options > Change advanced sharing settings..., the entry Turn on file and printer sharing should be selected, figure 6.26.
Exporting shares
Under Windows Explorer, right click on a folder and select Properties, figure 6.27.
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.
| File:Dialog-information.png | Note: Export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox does not propose adding mappings for exported drives. |
How to Make Shares in Mac OS X
Enabling Windows/SMB File Sharing
Open System Preferences > Sharing. Click the lock and enter an administrator's credentials to make changes.
Enable File Sharing. Click Options....
Check the option Share files and folders using SMB. This is the protocol used for Windows-style file sharing, figure 6.29.
Click Options....
| File:Dialog-information.png | Note: In Snow Leopard (10.6 or newer), you have to enable encrypted password support in Samba in the virtual machine. Inside the VM, edit /etc/samba/smb.conf and change the line under the "Authentication" section: encrypt passwords = false to encrypt passwords = true |
If this is not done, you encounter numerous failed password attempts. Other host operating systems and Samba/SMB/CIFS versions may not allow usage of unencrypted passwords.
Exporting Shares
Use the default shares for your account (Public, which is under /home/<user>/Public), or create new ones. Ensure your user account (who runs Eclipse) has Read and Write permissions, figure 6.30.
The Share name used in ESbox comes from the label under Shared Folders.
How to Make Shares in Linux
Enabling File Sharing
This also uses Windows-style file sharing. However, when the host and VM both run Linux, and you are using a modern version of Samba (3.x), POSIX file semantics are supported, so there is no loss of functionality (permissions, softlinks, and so on are preserved). Ensure that the samba package is installed from your distribution's package repository and that /etc/samba/smb.conf file exists.
Exporting Shares (Manual)
Method 1
If you are in the sambashare group, you may define a user share directly. This is done by adding an entry to /var/lib/samba/usershares (or, to the path defined by the usershare path option in /etc/samba/smb.conf file. Try testparm -s -parameter-name='usershare path' to see the setting).
Add a text file to this directory whose name is the Share name (for example, public). Specify its contents like this:
#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
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.
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.
Such shares are created as user shares, as described above.
Troubleshooting
Shared folder configuration problems
If you cannot mount to shared folders published from Windows, and you get the error mount error 12 = cannot allocate memory, then this is a host issue. Certain virus scanners may reset a registry setting to an inappropriately low value, making it impossible to export shares. You can fix this in your Windows registry.
Edit the key HKEY_ LOCAL_ MACHINE\System\CurrentControlSet \Services\LanmanServer\Parameters\IRPStackSize. Define it as a DWORD value (if missing). Set it to a value in the decimal range 15 to 18. The documentation is unclear what this value indicates, but it is probably a power-of-two. It may require some experimentation. The new setting will only be read when the sharing service is restarted. You may do this via Control Panel > Administrative Tools > Services > Server and restart, or if you have got more time to spare, reboot your system.
Also see the 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.
Setting up X Server
Setting up X Server on Windows
ESbox has been tested with the Cygwin/X server. Cygwin/X server is recommended since Cygwin is required also for other functionality like SSH.
| File: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 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.
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.
| File: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. |
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.
You can also see the combined warning if both changes are needed, figure 6.35.
How to change colour depth in Windows XP
Right-click the desktop, and then click Properties, figure 6.36.
Click the Settings tab.
Click the drop-down list in the Color Quality field and select Medium (16 bit).
Click OK, figure 6.37.
How to change colour depth in Windows Vista
Right-click the desktop, and then click Personalize, figure 6.38.
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.
How to change the display colour depth in Windows 7
Open the Control panel (Start > Control Panel), figure 6.41.
Click Adjust screen resolution under Appearance and Personalization, figure 6.42.
Click Advanced settings, figure 6.43.
Click the Monitor tab, figure 6.44.
Under Colors, select High Color (16 bit), and then click OK.
Setting up X Server on Mac OS X
Installing the server
The Xephyr server is recommended since it tracks the newest X server extensions used by Fremantle. Find this in the Xquartz project.
Runtime display requirements for Fremantle SDKs
Fremantle requires a 16-bit color depth for the display. Because Xephyr X11 server uses the default display depth from the host PC operating system you will see Eclipse dialog with warning if you launch Eclipse IDE in some other than 16-bit display mode. Set up your host PC display to have Thousands of colours in the System Preferences > Display field.
| File: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 6.45.
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.