Setting Up Shared Folders

Overview

Shared folders are needed when you run ESbox with a virtual machine outside the Debian Linux/x86 host. (See Using Virtual Machines for the primary documentation on virtual machines.)

In this configuration, the Maemo SDK (build tools, rootstrap, etc) 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 VM project). See the "How to Make Shares..." sections below.
  • Configure: you must tell ESbox what shares you have configured on the ESbox > Build Machines preference page under the Shared Folders pane. See the "Default Shared Folders Configuration" section below.

See a diagram explaining how this works in an example Win32 configuration here.

Sharing Eclipse Projects

In Eclipse, projects are traditionally created in the host filesystem*. 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:\maemo\shared". You create projects somewhere inside this tree. The share should have 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 may 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's best to select a directory which 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.


[*] 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 ESbox uses.

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, etc. 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 *.

This kind of sharing is not required for normal build, launch, or debug operations.

WARNING: 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 host's SMB/CIFS server, but Windows at least does not easily allow you to specify an alternate CIFS port with programs like "net use". Also, in MacOS 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 VM images export these shares by default.


[*] 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 due to time constraints and limitations in CDT 5. In any case, it's worthwhile to expose the SDK contents to the host so you can browse Maemo headers in the editor.

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 will map the same no matter which target you're 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 will 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. But 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).

Enable sharing services

Be sure to enable Windows File & Print Sharing. (I don't have a screenshot for this, but 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...":

Folder > Sharing and Security...

You will see a dialog for configuring a share:

Configured share dialog

Check "Share this folder".

Edit the "Share name" if needed. You need to enter the same value in the Shared Folders page. Usually this is the same as the last segment of the shared folder.

For "User limit", you may choose to limit the number of users. (ESbox will attempt to share a folder into a VM only once, even if you have multiple mappings established, by using bind mounts to mirror the original mount.)

Edit the "Permissions" and ensure that your local user account (who runs Eclipse) has Full Control (change and read). The build process needs to write object files, dependencies, and executables:

Permissions settings

Note: export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox will 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.

Vista Network and Sharing Center

Exporting shares

Under Windows Explorer, right click on a folder and select "Share...":

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

Setting user permissions

Note: export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox will 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.

Change sharing options

Exporting shares

Under Windows Explorer, right click on a folder and select Properties:

Right click > Properties

Select Share

File properties

Ensure that your local user account (who runs Eclipse) is in the share list, and has Permission Level = Owner (read and write). The build process needs to write and delete object files, dependencies, and executables.

File sharing

Note: export a single folder rather than a drive. It is inherently unsafe to export entire drives, and ESbox will not propose adding mappings for exported drives.

How to Make Shares in MacOS 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.

Enabling SMB sharing

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 not done, you will encounter numerous failed password attempts. (Other host OSes and host Samba/SMB/CIFS versions allow for 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.

Share preferences

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. But when the host and VM both run Linux, and you're using a modern version of Samba (3.x), POSIX file semantics are supported, so there is no loss of functionality (permissions, softlinks, etc. are preserved).

Ensure that the "samba" package is installed from your distribution's package repository and that /etc/samba/smb.conf 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. Try "testparm -s --parameter-name='usershare path' " to see the setting).

Add a text file to this directory whose name is the Share name (e.g. "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.

(Note: I don't know what is the format of "usershare_acl", but this particular string seems to be used widely.)

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

(substituting appropriate values for "path" and selecting 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 the UI, by using the "Sharing Options" item on a folder's context menu:

Folder > 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're 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.

GNOME Sharing Dialog

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

Troubleshooting

  • Shared folder configuration problems
    • If you cannot mount to shared folders published from Windows, and you get the error "mount error 12 = cannot allocate memory", then this is a host issue. Certain virus scanners may reset a registry setting to an inappropriately low value, making it impossible to export shares. You can fix this in your Windows registry.
    • Edit the key
      HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\LanmanServer\Parameters\IRPStackSize

      Define it as a DWORD value (if missing). Set it to a value in the decimal range 15 to 18. (The documentation is unclear what this value indicates, but it's 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've got more time to kill, 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 s in the future rm -f *.o helloworldmake: 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. (Frankly, there is not consistent behavior 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's unlikely you'll be 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 -- but Windows doesn't provide an obvious way to use SMB with different ports. From what I know, you'd need to set up some sort of virtual host over SSH to forward SMB traffic. Any tips are welcome :) )
  • Autotools projects fail to build Makefile?
    • If you have created or imported an autotools-based project, and autoconf and configure run, but make fails with:

      make: *** No rule to make target `all'. Stop.

      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 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 will guide you through the process of repairing the installation.