<type>documentation</type>
<domain>debug</domain>
<id>attaching-and-detaching</id>
<title>Attaching and Detaching</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Debug processes normally connect to Wing automatically during startup. However, Wing can
also attach to debug processes that are not already connected with the IDE. There are two
cases where this is useful:

**(1)** When an externally launched process that uses ``wingdbstub`` (as described in
section `Debugging Externally Launched Code
<ref:debug/debugging-externally-launched-code>`__) cannot reach the IDE at startup, for
example because the IDE is not yet running or was not configured to accept debug
connections.

**(2)** When a process attached to the IDE is disconnected using ``Detach from Process``
in the ``Debug > Processes`` sub-menu.

**Detaching**

``Detach from Process`` in the ``Debug > Processes`` sub-menu detaches from the current
debug process. ``Detach from All Processes`` detaches from all currently connected 
debug processes.

Whenever a process is detached, it continues to run outside of the debugger, without
stopping at any breakpoints or exceptions. If a process is paused in the debugger when it
is detached, the process will start running again immediately after the IDE disconnects.

**Attaching**

``Attach to Process`` in the ``Debug > Processes`` sub-menu displays a dialog that
contains known processes that were previously attached to Wing, and any additional
host/port pairs given with the `Debugger > Advanced > Common Attach Hosts
<script:show_preferences_gui#prefname="debug.attach-defaults">`__ preference. You may also
type in a host/port value here (see ``Identifying Processes`` below).

Once you are attached to a process, it continues running until it reaches a breakpoint,
unhandled exception, or ``Pause`` is used.

**Identifying Processes**

When `debugging externally launched code <ref:debug/debugging-externally-launched-code>`__
in Wing Pro, the ``kAttachPort`` constant in ``wingdbstub.py`` sets the port on which the
debug process will listen for attach requests from Wing.

If there are multiple concurrent processes and the specified port is in use then a random
port number will be used instead. This port number will be communicated to the IDE if the
debug process succeeds in connecting to it at startup, so the process can be listed in the
``Attach to Process`` dialog. Otherwise, you must use a unique value for the
``kAttachPort`` for each process.

**Access Control**

Wing creates a security token that is used to control who can attach to debug processes.
As long as your debug process is running as the same user and on the same host as the IDE,
attach and detach should work without any additional configuration.

If you run your debug process as a different user, or on a different machine than the IDE,
you will need to copy the file ``wingdebugpw`` from your `Settings Directory
<ref:install/user-settings-dir>`__ into the same directory as your copy of
``wingdbstub.py``.
