Importing the Debugger
The following step-by-step instructions can be used to start debugging in externally launched code that is running on the same machine as Wing:
- Copy wingdbstub.py from the install directory listed in Wing's About box into the same directory as your debug program.
- In some cases, you will also need to copy the file wingdebugpw from your User Settings Directory 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.
- At the point where you want debugging to begin, insert the following source code: import wingdbstub Depending on your code base, you may need to be cautious about whether this statement is reached by multiple processes. If this happens, the first process will connect to Wing and the second one will fail to connect and continue running without debug. If you are debugging code in an embedded Python instance, see the notes in Debugging Embedded Python Code.
- Make sure the Wing preference Accept Debug Connections is turned on, to allow connection from external processes.
- Set any required breakpoints in your Python source code.
- Initiate the debug program from outside Wing, for example with a page load in your web browser, if the program is a web app. You should see the status indicator in the lower left of the main Wing window to yellow, red, or green, as described in Debugger Status. Make sure that you are running the Python interpreter without the -O option. The debugger will not work when optimization is turned on.
- The debugger should stop at the first breakpoint or exception found. If no breakpoint or exception is reached, the program will run to completion, or you can use the Pause command in the Debug menu.
In some cases, you may wish to enable termination of debug processes that were launched from outside of Wing. By default, Wing recognizes externally launched processes and disables process termination in these cases unless the Kill Externally Launched preference is enabled.
If you have problems making this work, try setting kLogFile variable in wingdbstub.py for log additional diagnostic information.
Whenever the debugger cannot contact Wing (for example, if the IDE is not running or is listening on a different port), the debug program will be run without debugging. This is useful since debug-enabled CGIs and other programs should work normally when Wing is not present. However, you can force the debug process to exit in this case by setting the kExitOnFailure flag in wingdbstub.py. To attach to processes started without debug, see Attaching (only available in Wing Pro).