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

If you are manually configuring remote debugging without 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,
~~~
and the full path to your source code is not the same on both hosts, and the automated
file identification system described in the previous section won't work for your case,
then you will need to create a mapping that tells Wing where it can find your source files
on each host. This is done with the `Debugger > Network > 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**

If multiple matches are found for a given remote file, Wing uses the most specific match,
with the longest remote directory specification. Matches that point to existing local
files are preferred over non-existing ones, even if the match is more general.

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.

**Trouble-shooting**

When in doubt, an easy way to determine the correct file path to use is to place ``assert
0`` into a file and refer to the traceback shown in the ``Exceptions`` tool in Wing when
the file is debugged via ``wingdbstub``.  This can be used to set up the location map
correctly, assuming you know the local location of the file.

