Wing remote debugging notes

I recently had to track down a problem by remote debugging from a tinderbox machine to Wing running here on my home workstation. It wasn't hard to set up, and really helped in figuring out the problem, so I'm writing up the steps.

Here, Wing machine is the machine you intend to run the Wing IDE on; target machine is where you'll run Chandler; and Chandler directory is the top of your Chandler source tree, the directory where "Chandler.py" is.

Clarity begins at home

First, if you haven't already, make sure you can successfully debug when the Wing machine and the target machine are the same, and you're starting Chandler with the --wing option (since this is a little different than starting Chandler from within Wing).

Here's Wingware's docs about this: http://wingware.com/doc/debug/importing-the-debugger

Find your Wing install directory - depending on your platform, it'll be something like:

• Windows: C:\Program Files\Wing IDE 3.0
• Mac: /Applications/WingIDE-Professional-3.0.1/WingIDE/Contents/MacOS
• Linux: /usr/lib/wingide3.0

You'll know you've found it when you see a file called "wingdbstub.py" there - note the directory, and put a copy of this file in your Chandler directory.

You'll probably need to edit the copy of this file a little: it's well-commented, so read it. I've made these tweaks to mine (and I mark each with a comment with my initials, so I can tell what I've changed):

• kWingHostPort: this comes set to "localhost:50005", but I change it to my Wing machine's actual IP address. (This may not be required).

• kLogFile: set this to:

  os.path.join(os.path.dirname(__file__), "wingdb.log")

  because this is how you'll figure out why things are going wrong!

• kExitOnFailure: make this 1 because if you're trying to debug, you really don't want Chandler to continue to start up if the debugger session can't be started!

• WINGHOME: should point at the Wing install directory you found above.

Run Wing on your local machine, and open your Chandler project.

Choose Edit -> Preferences (not Project Preferences!), and under the Debugger section, click on External/Remote.

• Make sure "Enable Passive Listen" is checked.
• Make sure "Server Host: All valid interfaces" is selected.
• Click OK.

At the bottom left corner of the Wing application window, you should see a little ladybug icon - it should be white (meaning "listening"), and if you point at it, a tooltip will confirm this.

At this point, you should be able to run Chandler from a command line with the --wing option; shortly after Chandler starts, you'll see the ladybug turn green (meaning that a debugging session is underway). Try setting a breakpoint in Chandler, maybe in application/Application.py in wxApplication.OnIdle(), and make sure Chandler hits it. If it doesn't, solve this problem before going further - looking in "wingdb.log" in your Chandler directory can be helpful, as can Wing's "Messages" tab (usually found in the lower tool box panel in the Wing main window). Ask for help in #chandler if you can't get this working.

Remote debugging

Local debugging is fine, but there are situations where running Chandler on a different target machine is the only way to go:

• You're debugging a problem closely involved with handling of mouse/keyboard or update events; Wing on the same machine can affect the process being debugged.
• You're debugging a failure that only occurs (or occurs more reliably) on a platform other than your main Wing machine.
• You're debugging a hard-to-reproduce failure on a tinderbox.

Here's more helpful info from Wingware: http://wingware.com/doc/debug/remote-debugging

The target machine needs to have a copy of Wing on it (same version as your Wing machine's!), though it doesn't have an activated license: just download and install it normally, but don't bother running it.

It's best if Chandler is checked out from SVN on both your Wing machine and your target machine - this is the easiest way to make sure the source trees match identically. (More on this below, but for now, the trees should match and be free of local changes: get the debugging setup working before you start trying to fix whatever the bug is!)

The target machine's Chandler directory needs a copy of wingdbstub.py, too: you can copy the one you made above -- be sure to update WINGHOME if Wing is installed in a different place on the target machine, and kWingHostPort will really need to be an actual IP address.

Also, you'll need to copy the "wingdebugpw" file from your Wing preferences directory on your Wing machine (it's something like ~/.wingide3 on Mac or Linux, or c:\Documents and Settings\(you)\Application Data\Wing IDE 3\ on Windows) to the Chandler directory on the target.

You'll need to make a few changes on the Wing machine, too:

• File mappings, part one: If your Chandler directory (where Chandler.py is) is not at the same location on both machines, you'll need to set up a mapping in Wing's Debugger -> External/Remote preferences panel: click Insert under Location Map, enter the IP address of your target machine, click "Specify mapping", and enter the paths. (Handy tip: all the Preferences windows are growable, and the textboxes get larger if you widen the window!) Note: If one or both machines is running Windows, you might need to use a lowercase drive letter and backslashes in the paths - if you have trouble here, ping me and we'll work this out.
• File mappings, part two: If the two machines aren't running the same OS, you'll need separate mappings for your Chandler directory and the python2.5 directory under "release" (that is, the directory where python's "site-packages" subdirectory is). Also, if you explicitly set CHANDLERHOME and CHANDLERBIN to different places, you'll need a mapping for the $CHANDLERBIN/release on both machines as well. (Not having the right mappings set up can lead to two problems: Wing will put up annoying alerts about not being able to locate source files, and breakpoints won't get set right for files that aren't mapped properly.)
• If you have a firewall running on the Wing machine, open port 50005 to Wing on it (or just turn it off).

Finally, if you're doing the long-distance debug thing, there's more to do:

• I work at home, so my development machine is behind a NAT gateway/firewall. I had to configure it to forward port 50005 to my development machine.
• You'll want to set up an SSH server running on my development machine, and my home firewall forwards the SSH port to my Wing machine (I use an unusual SSH port, but the normal port 22 works fine) - see below for why this is useful.
• The tinderbox machines are behind OSAF's NAT gateway/firewall as well: when I was debugging Chandler running on a tinderbox target machine, I had to figure out the IP address that that firewall used, and use that address when setting up Wing.

A few more random tips:

• I used VNC, tunnelled through SSH, to get from my home machine to the tinderbox. This means something like

  ssh stearns@paniolo.osafoundation.org -L 5900:dev-imac1:5900

  to set up the tunnel, then VNC to "localhost:0".

• To figure out the ip address of OSAF's firewall, I established that VNC connection, opened a web browser, opened a page on public web server that I have access to, and looked at that web server's logs. You can probably come up with a simpler way.

• For breakpoints to work right, it's important that the source files be identical between machines. As I debugged, I found myself needing to try out different edits: I always only edit the source files on my Wing machine (which is nice, because I can do it in Wing), then I used this command in a shell on the target machine to sync up (with the current directory set to the Chandler directory):

  svn revert -R .; ssh stearns@my.home.domain.com "cd /home/stearns/chandler; svn diff" | patch -Nup0

  This discards any source changes on the target machine, then runs "svn diff" remotely to grab the changes from my development machine, piping them to patch the local tree on the target machine. (Don't forget to save in Wing on the Wing machine, first!)

-- BryanStearns - 16 Nov 2007