Configuring wingdbstub

Index of All Documentation » Wing Pro Reference Manual » Advanced Debugging Topics » Debugging Externally Launched Code »


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 File Properties, and Launch Configurations 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 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 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 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.

    See 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 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 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.