<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>

.. note::

  This section is relevant only 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,
~~~
  which automates the process of remote file access, and are instead manually configuring
  a file location map for remote debugging.
  
The best way to understand the location maps used for manual configuration of
remote debugging is to inspect a few examples.

**Defaults Explained**

The default value for the `Debugger > Advanced > 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 OS X 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 machine. 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 OS X 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 OS X 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 OS X
remote host with IP address ``192.168.1.1``. As in the previous example, 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: /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.
