<type>documentation</type>
<domain>debug</domain>
<id>debugging-externally-launched-code</id>
<title>Debugging Externally Launched Code</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

This section describes how to start debugging from a process that is not launched by Wing.
Examples of code that must be launched externally include tasks running under a web server
and embedded Python scripts running inside a larger application.

The following instructions can be used to start debugging in externally 
launched code that is running on the **same machine** as Wing:

1) Copy ``wingdbstub.py`` from the install directory listed in Wing's 
   `About <script:about-application>`__ box into the same directory as 
   the code you want to debug.  Make sure that ``WINGHOME`` inside 
   ``wingdbstub.py`` is set to the full path of your Wing installation.
   
2) In some cases, you will also need to copy the file ``wingdebugpw``
   from your `Settings Directory <ref:install/user-settings-dir>`__ into the same
   directory as ``wingdbstub.py``. This is needed when running the debug
   process as a different user or in a way that prevents the debug process
   from reading the ``wingdebugpw`` file from within your User Settings
   Directory.

3) At the point where you want debugging to begin, insert the following 
   source code:  ``import wingdbstub``.  If you are debugging code in 
   an embedded Python instance, see the notes in `Debugging Embedded 
   Python Code <ref:debug/debugging-embedded-code>`__.
   
4) Make sure the `Debugger > Listening > Accept Debug Connections
   <script:show_preferences_gui#prefname="debug.passive-listen">`__ preference is 
   turned on, to allow connection from external processes.

5) Set any required breakpoints in your Python source code by clicking
   on the breakpoint margin to the left of the code in Wing, or with
   the breakpoint items in the ``Debug`` menu.
   
6) Initiate the debug program from outside Wing in a way that causes it to 
   ``import wingdbstub`` and reach a breakpoint or exception.  You should see the 
   status indicator in the lower left of Wing's window change to yellow, red, or 
   green, as described in `Debugger Status <ref:debug/status>`__.   When a
   breakpoint is reached, Wing should come to the front and show the file where
   the debugger has stopped.  If no breakpoint or exception is reached, the 
   program will run to completion, or you can use the ``Pause`` command in 
   the ``Debug`` menu.

If you have problems making this work, try setting the ``kLogFile`` variable
in ``wingdbstub.py`` to log additional diagnostic information.
