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

The best way to understand location maps, used for low-level manual configuration of
remote debugging, is to inspect a few examples.

**Defaults Explained**

The default value for the `Debugger > Network > Location Map
<script:show_preferences_gui#prefname="debug.location-map">`__ preference contains one
entry for ``127.0.0.1`` where the mapping is set to ``Same as localhost``. This treats
the full paths to files on both the remote host and local host as identical.

**Two Linux or macOS Hosts**

In this example Wing is running on ``desktop1`` and debugging some code on ``server1``
with IP address ``192.168.1.1``. Files located in ``/home/apache/cgi`` on ``server1`` are
the same files seen in ``/svr1/home/apache/cgi`` on ``desktop1`` because the entire file
system on ``server1`` is being shared via NFS and mounted on ``desktop1`` under ``/svr1``.

To support this example, the following would be added to the location map preference::

  Remote IP 192.168.1.1 - Remote: /home/apache/cgi, Local: /svr1/home/apache/cgi

To enter this change in Wing's preferences, you would add ``192.168.1.1`` as a new
``Remote IP Address``, select ``Specify Mapping``, and enter a single mapping with
``Remote`` set to ``/home/apache/cgi`` and ``Local`` set to ``/svr1/home/apache/cgi``.

**Two Hosts Using an SSH Tunnel**

When using an `SSH tunnel <ref:debug/ssh-tunnels>`__, the IP address to which you add a
mapping is always ``127.0.0.1`` because the tunnel forwards traffic in such a way that the
IDE sees the connection as coming from the local host. The remote and local file paths
given are the same as for the other examples given here. For the previous example it would
be::

  Remote IP 127.0.0.1 - Remote: /home/apache/cgi, Local: /svr1/home/apache/cgi

**IDE on Linux or macOS with Debug Process on Windows**

If you are debugging between two hosts of different type, the native path name format is
used for the ``Remote`` specification and forward slashes are always used for the
``Local`` specification.

For example, the following entry would be used when running Wing on a Linux or macOS host and
the debug process on a Windows host with ip address ``192.168.1.1``, where the Linux or OS
X directory ``/home/myuser`` is being shared via Samba to the Windows machine and mapped
to the ``e:`` drive::

  Remote IP 192.168.1.1 - Remote: e:\src, Local: /home/myuser/src

**IDE on Windows with Debug Process on Linux/Unix**

In this example, Wing is running on Windows and the debug process is on a Linux or macOS
remote host with IP address ``192.168.1.1``. As in the previous example, the Linux or macOS
directory ``/home/myuser`` is being shared via Samba to the Windows machine and mapped to
the ``e:`` drive::

  Remote IP 192.168.1.1 - Remote: /home/myuser/src, Local: e:/src

Note the use of forward slashes in the the ``Local`` specification even though the file is
on a Windows machine.

**Two Windows Hosts**

In this example, Wing is running on Windows and the debug process on another Windows machine
with IP address ``192.168.1.1``.  The host where Wing is running has mapped the entire
remote host's ``c:`` drive to ``e:``::

  Remote IP 192.168.1.1 - Remote: c:\src, Local: e:/src

**Two Windows Hosts using UNC Share**

This example is the same as the previous one, except that the UNC style path is used 
for the host where Wing is running::

  Remote IP 192.168.1.1 - Remote: c:\src, Local: \\server\share\dir

Notice that backslashes are used in the ``Local`` specification when entering
UNC style paths.

**Windows and cygwin**

In this example Wing runs on a Windows machine that also has cygwin installed. The cygwin
files at ``/c/src/test`` are the same as the directory ``c:\\srctest`` on the Windows
side::

  Remote IP 127.0.0.1 - Remote: /c/src/test, Local: c:/srctest
  
Notice that the IP address is 127.0.0.1 since cygwin runs on the same machine as Windows.

**macOS Host and Raspberry Pi accessed via SSH Tunnel**

In this example, Wing is running on a macOS host that is connected to a Raspberry Pi
through an `SSH tunnel <ref:debug/ssh-tunnels>`__. The files in ``/home/pi/`` on the
Raspberry Pi match those in ``/Users/pitest/src/`` on the machine where Wing is running::

  Remote IP 127.0.0.1 - Remote: /home/pi, Local: /Users/pitest/src

Notice that because of the use of an SSH tunnel, the remote IP address is reported
as 127.0.0.1 and not the IP address of the Raspberry Pi.

