<type>documentation</type>
<domain>proj</domain>
<id>remote-hosts</id>
<title>Remote Development Features</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>

Once you have your remote project set up, you should be able to edit, debug, test,
and otherwise work with Wing in the same way as you in the local case.

**Editing**

Editing on a remote host is no different than editing on a local host, except
that in some cases the contents of a file may take a bit longer to appear when
it is first opened.

**Debugging**

Debugging also works the same way as for local files. Wing will initiate the debug
connection automatically through its SSH tunnels to the remote host. File names will be
shown in the form ``hostid:filename`` but otherwise debugging works the same way as 
on the local host.

To debug on several different remote hosts, use ``Launch Configurations`` in the
``Project`` menu to create debug configurations on each host.  This is done in the
same way as for ``Project Properties``, by setting ``Python Executable`` under the
``Python`` tab to ``Remote``.  Then set up a ``Named Entry Point`` that pairs a 
file on that remote host with a launch configuration for the same remote host.

Whether you use the Project-wide settings or a launch configuration, the file you
debug needs to be stored on the selected remote host.  You cannot debug a file from
one host on another host using this style of remote debug configuration.

When debugging on a remote host, the ``Debugger > I/O > Use External Console`` 
preference is ignored and I/O always appears in the ``Debug I/O`` tool.  If a
remote process needs to run in a different console, start it there and initiate
debug from your code as described in `Debugging Externally Launched Remote Code 
<ref:debug/remote-debugging>`__.

The ``Debugger > Diagnostics`` preferences are also not used when debugging on a 
remote host. The following environment variables can be used instead to collect debugger
diagnostics. These should only be used at the request of Wingware Technical Support, and 
the resulting log file can be emailed along with your bug report to ``support@wingware.com``:

**WINGDB_LOGFILE** can be used to set up a diagnostics log file when trouble-shooting
problems with the debugger. The environment variable should be set to the full path of the
log file on the remote host.

**WINGDB_LOGVERYVERBOSE** selects whether to print extremely verbose low-level logging.
This is almost never needed and will drastically slow down debugging.

**Debugging Externally Launched Code**

If you need to start your debug processes from outside Wing, as for services running on a
remote host, you can debug those processes by importing ``wingdbstub``. When you install
the remote agent, Wing writes a correctly configured copy of ``wingdbstub.py`` into the
remote agent's installation directory. To use it, follow the instructions in 
`Debugging Externally Launched Remote Code <ref:debug/remote-debugging>`__.

**Python Shell**

Once you have set ``Python Executable`` in ``Project Properties`` to a remote host,
you can restart the ``Python Shell`` from its ``Options`` menu to launch a shell
that is running on the remote host.

**Testing Remotely**

If remote files have been added to the ``Testing`` tool the unit tests can be run
or debugged as if they are on the same host as the IDE.

**Version Control**

If remote files are checked into a version control system, Wing should identify this
as it does for local files and include the appropriate tools in the ``Tools`` menu.
Version control features work the same way for remote files as for local files.
However, it may be necessary to configure version control for the remote host
using the ``VCS`` tab in ``Project Properties``.

Operations that access the version control repository (such as push and
pull) may not work due to lack of access to the necessary SSH keys.  There
are two possible solutions for this:

1) If the remote VCS command tries to display a password collection dialog,
   you can turn on the ``Forward X11`` option in your remote host configuration,
   so that the dialog will appear on the machine where Wing is running.  On
   Windows and macOS this requires installing an X11 server on the local machine.
   
2) You can forward the local host's SSH agent credentials to the remote host
   by adding ``ForwardAgent yes`` to your ``.ssh/config`` on the machine where 
   Wing is running.  It's best to limit this to the hosts that require it
   and you should do it only if you understand the security implications.

**OS Commands**

The ``OS Commands`` tool also supports working remotely with the ``Hostname`` property
under the ``Environment`` tab of ``Command Line`` style commands.  For ``Python File``
and ``Named Entry Point`` style OS Commands, the host name is inferred from the
location of the file being executed.
