<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``, ``Command Line``, or ``Activated
Env``, 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 select or create a remote host configuration from the ``Host`` menu.
This will ask for the same fields described in the previous section, for creation of a
remote host configuration. If you previously created a similar configuration, use the
``Recent Hosts`` drop down to copy that configuration.

Projects created from the ``New Project`` dialog are saved locally, which is the recommended
approach for storing remote projects.

Storing Project Files Remotely
..............................

In some cases, storing the project file on the remote host is useful. This can be done by
first creating a shared remote host configuration with the ``Remote Hosts`` dialog,
accessed from the ``Debug`` menu, then creating a new project using that shared
configuration, and finally choosing ``Save Project on Remote Host`` from the ``Project``
menu to store the project on the remote host. 

Note that this menu item is not shown if you do not have any shared remote host
configurations defined because there is no way to later open the project if you do not
have a shared locally stored remote host configuration for that host.

A regularly created local project can also be moved to a remote host with ``Save Project
On Remote Host``. 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.
