<type>documentation</type>
<domain>debug</domain>
<id>file-location-maps</id>
<title>Manually Configured File Location Maps</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

If you are not using Wing Pro's 
~~~if WINGPRO:
`Remote Hosts <ref:proj/remote-hosts>`__ feature
~~~
~~~if WINGPER:
`Remote Hosts <https://wingware.com/doc/proj/remote-hosts>`__ feature
~~~
for remote debugging and the full path to your source code is not the same on both
machines, you also need to set up a mapping that tells Wing where it can find your source
files on each machine. This is needed to convert between the file names reported by the
debugger for the remote host and the locations for the same files on the local host.

This is done with the `Debugger > Advanced > Location Map
<script:show_preferences_gui#prefname="debug.location-map">`__ preference, which lists
corresponding local and remote directory locations for each remote host's IP address.

Each host IP address in the location map is paired with one or more ``(remote_prefix,``
``local_prefix)`` pairs. The ``remote_prefix`` is the full path on the remote hosts's
file system using the file naming conventions for the remote host. The ``local_prefix`` 
is the full path of a local directory, using ``/`` forward slash as the separator
regardless of which OS Wing is running on (except when specifying UNC style paths
on Windows, in which case ``\`` backslash is used).

The best way to understand this is to look at the `Manually Configured Location Map 
Examples <ref:debug/file-location-map-example>`__.

**SSH Tunnels**

When using an SSH tunnel, the IP address entered into the ``Location Map`` preference is
the IP address of the host the IDE is running on, since the IDE thinks the connection is
coming from the local host. This is often ``127.0.0.1`` but on Windows it may instead be
the IP address for the host. This depends on the peer ip that is reported on the IDE side
for connections opened through the pipe.

**Details and Limitations**

When running Wing on Windows, UNC formatted file names such as ``\\machine\path\to\file``
may be used. In cases where setting up a persistent drive mapping is a problem, use a
``cmd.exe`` script with a ``net use`` command to map the drive on demand.

Note that making symbolic links on the client or server will not work as an alternative to
using this mapping. This is a side-effect of functionality in the debugger that ensures
that debugging works right when symbolic links are present. As a result, source file names
are always resolved to their actual full path location.

