<type>documentation</type>
<domain>debug</domain>
<id>wingdb</id>
<title>Using wingdb to Initiate Debug</title>
<date>$Date: 2006-05-24 22:44:59 -0400 (Wed, 24 May 2006) $</date>
<version>$Revision: 13097 $</version>
<product>pro+</product>

Debug can be started on the command line by running ``wingdb`` (or ``wingdb.exe`` on
Windows) from the top level of the Wing installation. These are invoked like the Python
command line, after setting some environment variables that tell Wing which Python
installation to use and how to connect to the IDE.

**Minimal Configuration**

First make sure that Wing is listening for debug connections by clicking on the bug icon
in the lower left and enabling ``Accept Debug Connections``.

Next set the environment variable **WINGDB_PYTHON** to the full path to the python or
python.exe to use. This is needed only if you do not want to use the default ``python``.

Now you can start debugging by running ``wingdb`` (or ``wingdb.exe``) as if it were
Python. Debugging should start and the process should connect back to Wing.

For example on Windows::

  set WINGDB_PYTHON=C:\Python38\python.exe
  "C:\Program Files (x86)\Wing Pro ~~MAJOR_VERSION~~\wingdb.exe" myscript.py arg1 arg2
  
On Linux::

  export WINGDB_PYTHON=python3.8
  /usr/lib/wingpro~~MAJOR_VERSION~~/wingdb myscript.py arg1 arg2
  
On macOS::

  export WINGDB_PYTHON=python3.8
  "/Applications/~~OSX_BUNDLE~~.app/Contents/Resources/wingdb" myscript.py arg1 arg2
  
**Advanced Configuration Options**

Other environment variables that control the debugger's behavior include:

**WINGDB_PYARGS** provides any arguments to send to Python itself. Do not use this for
arguments sent to your Python code. Those are specified on the command line instead.

**WINGDB_STEPINTO** is set to 0 or 1 to indicate whether to stop on the first line of code
(default=0)

**WINGDB_WAIT_ON_EXIT** controls whether the debug process should wait on exit for further
interaction with the debugger (default=don't wait)

**WINGDB_ENV_FILE** causes the debugger to load environment from this file and then exec
``sys.executable`` in the environment, rather than running in the inherited environment.
The environment file contains a sequence of byte strings, each separated by a ``'\0'`` byte.
The 1st of every pair is a key and the 2nd is the value. (default=run in inherited
environment)

**WINGDB_HOSTPORT** is the host:port where the IDE is running, if different than the
default of ``localhost:50005``. The host can be either a host name or an IP address and
the port is the one shown when the mouse is hovered over the bug icon in the lower left of
Wing's main window. We *strongly* recommend using Wing Pro's `Remote Hosts
<ref:proj/remote-hosts>`__ feature instead. Otherwise, you'll also need most of the
tedious manual configuration described in `Manually Configured Remote Debugging
<ref:debug/manual-remote-debugging>`__.

**WINGDB_SECURITYTOKEN** can contain the security token to use for authentication
with the IDE.  If not specified, the default is to read the token from the 
``wingdebugpw`` file in the user settings directory (the value used is the portion
after the ``:``).

**WINGDB_USERSETTINGS** is used only to find the debugger implementation if provided by an
update made while running Wing with a non-default `Settings Directory
<ref:install/user-settings-dir>`__, as specified using the ``--settings`` command line
argument (default=use the standard location for the directory)

**WINGDB_LOGFILE** is the full path to a diagnostic log file. Set this only at the request
of Wingware Technical Support. It will slow down the debugger (default=no logging)

**WINGDB_LOGVERYVERBOSE** controls whether to print extremely verbose low-level diagnostic
logging. Set this only at the request of Wingware Technical Support. It will *drastically*
slow down debugging (default=off)

The following env is relevant only for Python 3.12 and later:

**WINGDB_USELEGACYTRACERCORE** can be set to ``1`` to force Wing to always use the legacy
debugger core, rather than using the new optimized debugger core that is based on
debugging features found only in Python 3.12+.

The following optional envs are only used to support Python 2.5; in Python 2.6+
set PYTHONIOENCODING instead:
  
**WINGDB_STDOUT_ENCODING** sets the encoding to use for stdout

**WINGDB_STDIN_ENCODING** sets the encoding to use for stdin

