<type>documentation</type>
<domain>proj</domain>
<id>remote-hosts</id>
<title>Setting up Remote Projects</title>
<date>$Date: 2010-05-14 11:53:19 -0400 (Fri, 14 May 2010) $</date>
<version>$Revision: 22093 $</version>
<product-version>6+</product-version>
<product>pro+</product>

There are two ways to work with remote hosts: (1) a locally stored project file can
reference remote resources, and (2) a project file stored on a remote host and opened
remotely can transparently access resources on that remote host.

Local Project Files
-------------------

For projects stored locally that need to access resources on another host, the 
``Python Executable`` property in ``Project Properties`` is set to ``Remote`` to 
indicate that a project's Python resides on a remote host.  The remote host
configuration that is selected is typically an unshared configuration, so that
it is stored in the project and will be accessible if the project is moved 
to another machine.  Note, however, that remote host configurations may be 
specific to an individual machine's network environment, and may need to be
edited on other hosts.

After ``Python Executable`` has been set, other properties that reference files, such as 
``Initial Directory`` and ``Python Path``, will be resolved on the remote host.  The
``Browse`` buttons for those properties will browse the remote host, and paths will
be stored as partial paths relative to the configured ``Base Directory`` or as
full paths if located outside of the ``Base Directory``.  Paths on remote hosts are 
always expressed using forward slash ``/`` and will be converted as needed to the native 
separator on the remote host.

The selected remote host will also be used for adding files and directories to the
project. When a URL for a remote file or directory is shown, it will be in the form
``ssh://hostid/path/to/file.py`` where ``hostid`` is one of the configured ``Remote Host
IDs``. 

A locally stored project can include files and directories on multiple hosts, by adding 
several hosts and using ``Add Existing File`` and ``Add Existing Directory`` with each host.

Remote Project Files
--------------------

Projects stored on a remote host are opened with ``Open Remote Project`` in the 
``Project`` menu.  This menu item is not shown unless you have already created a shared 
remote host configuration.  Projects stored like this are normal Wing projects and
may also be opened locally, if Wing can also be run on the remote host itself.
In this case, ``Python Executable`` is simply set to ``Default`` or ``Custom``,
as if the project were stored locally.  Wing resolves all the resources in 
the project file in a way that allows it to access them on the host where
the project is stored.

If any remote host configurations are added to a remotely stored project, in order
to access other remote hosts, those configurations must work on the host where
the IDE is running.

Creating Project Files
----------------------

To set up a new project that accesses a remote host, use ``New Project`` in the
``Project`` menu and specify ``Connect to Remote Host (via SSH)`` as the project type.
This will ask for the same fields described in the previous section, for creation of a
remote host configuration. If you have already created a configuration previously, use the
``Recent Hosts`` drop down to copy that configuration.

The ``New Project`` dialog will offer to save the project either locally or on the
selected remote host. If it is stored locally, the entered remote host configuration will
be stored in the project file. If it is stored remotely, the configuration will be set up
as shared so it is always accessible on the local machine, so it can be used to open the
remote project.

A regularly created local project can also be moved to a remote host with 
``Save Project On Remote Host``` in the ``Project`` menu.  This menu item is
visible only if there is at least one shared remote host configuration.  Saving
the project in this way moves only the project file itself, and assumes that resources 
referenced by the project will also be available on the remote host, with the same 
relative paths from the project file.
