<type>documentation</type>
<domain>debug</domain>
<id>debug-server-configuration</id>
<title>Configuring wingdbstub</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

In some cases you may need to alter other preset configuration values at the start of
``wingdbstub.py``. These values completely replace the corresponding values set in
`Project Properties <ref:proj/project-properties>`__ `File Properties
<ref:proj/file-properties>`__, and `Launch Configurations <proj/launch-configs>`__ in
the IDE. Those are used only when the debug process is launched from Wing.

The following options are available:

* Set ``kWingDebugDisabled=1`` to disable the debugger entirely. This is equivalent
  to setting the ``WINGDB_DISABLED`` environment variable before starting debug.
  
* Set ``kWingHostPort`` to specify where Wing is listening for connections from externally
  launched debug processes, so the debugger can connect to it when it starts. This is
  equivalent to setting the ``WINGDB_HOSTPORT`` environment variable before starting debug.
  The default value is ``localhost:50005``.
  
  Note that hostname will still be ``localhost`` if you are debugging over an SSH tunnel,
  as will be the case if you are using a `remote host <ref:proj/remote-hosts>`__
  configuration. The SSH tunnel takes care of listening on ``localhost`` and then tunnels
  the connection to the host where the IDE is running.
  
  See `Manually Configured Remote Debugging <ref:debug/manual-remote-debugging>`__ for
  details on changing this value.

* Set ``kLogFile`` to write a diagnostic log of debugger activity to a file. Usually, you
  should set this only at the request of Wingware Technical Support. This is equivalent to
  setting the ``WINGDB_LOGFILE`` environment variable before starting debug (use a value 
  of ``-`` to turn off logging to file even if ``kLogFile`` is set).
  
  When setting this value to a file name, the file will be created if it does not exist.
  Similarly named files are created if multiple processes are being debugged, one for
  each process.
  
  Use ``<stdout>`` or ``<stderr>`` to write to Python's ``sys.stdout`` or ``sys.stderr``.
  Note that using ``<stderr>`` will cause problems on Windows if the debug process is not
  running in a console. 
  
* Set ``kEmbedded`` to ``1`` when debugging embedded scripts, so the debug connection will
  be maintained across script invocations, rather than closing the debug connection when 
  the script finishes. This is equivalent to setting the environment variable
  ``WINGDB_EMBEDDED``. See `Debugging Embedded Python Code
  <ref:debug/debugging-embedded-code>`__ for details.
  
* Set ``kAttachPort`` to define the default port at which the debug process will listen
  for requests to attach. This is available in Wing Pro only and is equivalent to setting
  the ``WINGDB_ATTACHPORT`` environment variable before starting debug.
  
  If this value is less than ``0``, the debug process does not listen for attach requests.
  Otherwise, the debugger listens on this port whenever the debug process is running
  without being connected to the IDE, as might occur if it initially fails to connect or
  if the IDE detaches from the process.
  
~~~if WINGPRO:
  See `Attaching and Detaching <ref:debug/attaching-and-detaching>`__ for details.
~~~
  
* Set ``kSecurityToken`` to the security token used to authenticate with the IDE before
  the debug connection is accepted.  This is the value in the ``wingdebugpw`` file 
  (the portion after the ``:``) in the `Settings Directory <ref:install/user-settings-dir>`__ 
  for the user that is running the IDE.  When this value is ``None`` the security
  token is located used ``kPWFilePath`` and ``kPWFileName`` as described below.
  
* Set ``kPWFilePath`` and ``kPWFileName`` tell the debugger where to find the security
  token file required for a debug connection to the IDE to succeed. This is equivalent 
  to setting the environment variables ``WINGDB_PWFILEPATH`` and ``WINGDB_PWFILENAME`` 
  before starting debug.
  
  ``kPWFilePath`` should be a Python list of strings containing directory names if set in
  ``wingdbstub.py`` or a list of directories separated by the path separator
  (``os.pathsep``) when sent by environment variable. The string ``$<winguserprofile>``
  may be used to specify the `Settings Directory <ref:install/user-settings-dir>`__
  for the user that is running the debug process.
  
  ``kPWFileName`` sets the file name to use for the security token.  The default is
  ``wingdebugpw``.

* Set ``WINGHOME`` to the Wing installation directory (or the name of Wing's ``.app``
  folder on macOS) so that ``wingdbstub.py`` can find the debugger.  This is equivalent
  to setting the environment variable ``WINGHOME`` before starting debug.
  
  For Windows and Linux, and for copies of ``wingdbstub.py`` in a remote agent
  installation, ``WINGHOME`` will usually be set automatically during installation. The
  value may need to be set on macOS, if Wing was installed from the ``.zip`` installer on
  Windows or the ``.tar`` installer on Linux, if running Wing from sources, or if
  configuring remote debug manually.
  
* Set ``kUseLegacyTracerCore`` to force Wing to use the legacy debugger core also with
  Python 3.12+, rather than using the new optimized core that uses Python 3.12+-specific
  language features.  This is the same as setting the ``WINGDB_USELEGACYTRACERCORE``
  environment variable.

Setting any of the above-described environment variable equivalents will override any
value given in the ``wingdbstub.py`` file.

