<type>documentation</type>
<domain>debug</domain>
<id>debug-with-sitecustomize</id>
<title>Starting Debug Automatically Using sitecustomize</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

It is possible to use Python's sitecustomize feature (provided by the `site
<https://docs.python.org/3/library/site.html>`__ standard library module) to automatically
start debugging all code that runs using a particular Python installation.

To set this up on the same host where Wing is running:

**(1)** Make a new directory ``sitecustomize`` and then add a file named ``__init__.py``
to the directory with the following contents:

.. python:: 

  from . import wingdbstub

This is the hook that will cause Python on the containers to load Wing's debugger.  It is 
loaded by Python's `Site-specific configuration hook <https://docs.python.org/3/library/site.html>`__.

**(2)** Configure a copy of Wing's ``wingdbstub.py`` to place into this ``sitecustomize``
directory.

You can find the master copy of ``wingdbstub.py`` at the top level of your Wing
installation (or on macOS in ``Contents/Resources`` inside ``WingPro.app``). If you don't
know where this is, it is listed as the ``Install Directory`` in Wing's ``About`` box.

You will need to make copy of this file to your ``sitecustomize`` package directory.

On macOS or if you installed Wing from the ``.zip`` or ``.tar`` installer, you will
need to set ``WINGHOME`` inside your copy of ``wingdbstub.py`` to the full path of your
Wing installation -- the same place you found the ``wingdbstub.py`` file.

**(3)** Move your ``sitecustomize`` directory into the ``site-packages`` directory in your
Python installation.

You can determine this value by starting Python and inspecting it with the following lines
of code:

.. python::

  >>> import os, sys, site
  >>> v = sys.version_info[:2]
  >>> print(os.path.join(site.USER_BASE, 'lib', 'python{}.{}'.format(*v), 'site-packages'))

This prints the location where you need to move your ``sitecustomize`` directory.

**(4)** Configure Wing to listen for externally initiated debug connections. This is done
by clicking on the bug icon |bugicon| in the lower left of Wing's window and enabling
``Accept Debug Connections``.

.. |bugicon| image:: icon:wingide-debug-status-none
  :class: inline-image

If your debug process spawns child processes that you also wish to debug, then you will
also need to open ``Project Properties`` from the ``Project`` menu and set ``Debug Child
Processes`` under the ``Debug/Execute`` tab to ``Always Debug Child Processes``.

Starting Debug
--------------

Wing should now debug any Python code run using your Python installation, not matter how
it is started. Python loads your ``sitecustomize`` before any other code is run, which
imports ``wingdbstub`` and thus starts debug and makes a connection to the IDE.

To temporarily disable debug without making any other changes, turn off ``Accept Debug
Connections`` again as described in step (4) above.

Remote Hosts and Containers
---------------------------

This technique also works to automatically start debug on a remote host or container.

On a remote host, first follow the instructions in `Debugging Externally Launched Remote
Code <ref:debug/remote-debugging>`__ to get remote debugging working. Then proceed with
the instructions above, using the copy of ``wingdbstub.py`` from the remote agent
installation on the remote host (usually ``~/.wingpro~~MAJOR_VERSION~~/remote-~~FULL_VERSION~~``).
That file is already pre-configured to work on your remote host.

On a container, first follow the instructions for `Working with Containers and Clusters
<ref:proj/container-intro>`__ and then set up your ``sitecustomize`` so it is mounted into
``site-packages`` on your container. You will need to edit your copy of ``wingdbstub.py``
to set ``WINGHOME`` to ``/wingpro~~MAJOR_VERSION~~`` and ``kHostPort`` to
``<hostname>:50005`` where ``<hostname>>`` is replaced with the name of the host system as
viewed from the container.  For Docker, this is usually ``host.docker.internal:50005``.
Note that this assumes you are using the default debug port in Wing; if not, use the
value set with the ``Debugger > Listening > Server Port`` preference.

Trouble-Shooting
----------------

If you can't get the debugger to connect, try setting ``kLogFile`` in your copy of
``wingdbstub.py`` to ``"<stderr>"`` or a valid log file name. You can email this output to
`support@wingware.com <mailto:support@wingware.com>`__ for help.
