Note
"The best solution for debugging Zope and Plone"
-- Joel Burton, Member, Plone Team
Wing IDE is an integrated development environment that can be used to
develop, test, and debug Python code running under Zope2 or Zope3. Wing
provides auto-completion, call tips, and other features that help you write,
navigate, and understand Zope code. Wing's debugger can be used to debug code
in the context of the running Zope server, in response to page loads from a
browser, and can work with Zope's code reloading features to achieve a very
short edit/debug cycle.
Wing's code intelligence and debugging support work with Products, External
Methods, file system-based Scripts and Zope itself. Wing IDE is also useful
for Zope-based frameworks like Plone (see Plone Quickstart).
For more information on Wing IDE see the product overview. If you do not already have Wing IDE
installed, download a free trial now.
To get started using Wing, refer to the tutorial in the Help menu in Wing
and/or the Wing IDE Quickstart Guide.
Before Getting Started
Note: This guide is for Zope2 users. If you are using Zope3, please
try z3wingdbg by Martijn Pieters or refer to Debugging Externally
Launched Code in the users manual to set up Zope3 debugging manually.
Limitations: Wing IDE cannot debug DTML, Page Templates, ZCML,
or Python code that is not stored on the file system.
Security Warning: We advise against using the WingDBG product
on production web servers. Any user connected to the Wing IDE debugger
will (unavoidably) have extensive access to files and data on the system.
Upgrading from earlier Wing versions
If you are upgrading from an older version of Wing and have previously used
Wing with your Zope installation(s), you need to manually upgrade WingDBG
in each Zope instance. Otherwise, debugging may fail.
The easiest way to do this is to go to the Zope Control Panel, click on Wing
Debug Service, and then Remove the control panel. Then restart Zope. Next,
go into your Wing project's Extension Tab, verify that you've got the
Zope Instance Home set correctly, and press Apply. This will offer to
re-install WingDBG with the latest version and will configure it to point
to the new version of Wing.
Quick Start on a Single Host
To use Wing IDE with Zope running on the same host as the IDE:
- Install Zope -- You can obtain Zope from zope.org. Version
2.5.1 or newer will work with Wing.
- Install Wing IDE -- You will need Wing IDE 2.1 or later.
See Installing for details.
- Configure Wing IDE -- Start Wing, create or open the project you
wish to use (from the Project menu). Then use the Extensions
tab in Project Properties to enable Zope2/Plone support and to
specify the Zope2 Instance Home to use with the project. Wing
will find your Zope installation by reading the file etc/zope.conf
in the provided Zope instance. Once you press Apply or OK in the Project
Properties dialog, Wing will ask to install the WingDBG product and will
offer to add files from your Zope installation to the project.
If your zope instance is generated by buildout, set the main debug file to
the bin/instance file (bin\instance-script.py on Windows) in your
buildout tree by opening the file in Wing and select Set Current as Main
Debug File in the Debug menu. This will set up the effective sys.path
for the instance.
- Configure the WingDBG Product -- Start or restart Zope and
log into http://localhost:8080/manage (assuming default Zope
configuration). The Wing Debugging Service will be created automatically
on startup; you can find it under the Control Panel of your server.
If the Wing Debugging Service does not appear in the Control Panel,
you may need to enable product loading in your zope.conf file by
changing enable-product-installation off to
enable-product-installation on.
Starting the Debugger
Proceed to the Wing Debugger Service by navigating to the Control Panel, then
selecting the 'Wing Debugging Service'. Click in the "Start" button. The Wing
IDE status area should display "Debugger: Debug process running".
Note that you can configure WingDBG to start and connect to the IDE automatically
when Zope is started from the Advanced configuration tab.
Problems? See the Trouble-Shooting Guide below.
Test Drive Wing IDE
Once you've started the debugger successfully, here are some things
to try:
Run to a Breakpoint -- Open up your Zope code in Wing IDE and set
a breakpoint on a line that will be reached as the result of a browser
page load. Then load that page in your web browser using the port number
displayed by the Zope Management Interface after you started the
debugger. By default, this is 50080, so your URL would look something
like this:
http://localhost:50080/Rest/Of/Usual/Url
Explore the Debugger Tools -- Take a look at these tools available
from the Tools menu:
- Stack Data -- displays the stack, allows selecting current stack frame,
and shows the locals and globals for that frame.
- Debug Probe (Wing Pro only) -- lets you interact with your paused debug process using
a Python shell prompt
- Watch (Wing Pro only) -- watches values selected from other value views (by right-clicking
and selecting one of the Watch items) and allows entering expressions
to evaluate in the current stack frame
- Modules (Wing Pro only) -- browses data for all modules in sys.modules
- Exceptions -- displays exceptions that occur in the debug process
- Debug I/O -- displays debug process output and processes keyboard input
to the debug process, if any
Continue the Page Load -- When done, select Start / Continue from the
Debug menu or toolbar.
Try Pause -- From Wing, you can pause the Zope process by pressing
the pause icon in the toolbar or using Pause from the Debug menu. This is
a good way to interrupt a lengthy computation to see what's going on.
When done between page loads, it pauses Zope in its network service code.
Other Features -- Notice that Wing IDE's editor contains a source
index and presents you with an auto-completer when you're editing
source code. Control-click on a source symbol to jump to its
point of definition (or use Goto Selected Symbol in the Source menu).
Wing Pro also includes a Source Assistant and Source Browser. The
Source Assistant will display context appropriate call tips and documentation.
Bring up the Source Browser from the Tools menu to look at the
module and class structure of your code.
Setting Up Auto-Refresh
When you edit and save Zope External Methods or Scripts, your changes
will automatically be loaded into Zope with each new browser page load.
By default, Zope Products are not automatically reloaded, but it is
possible to configure them to do so. This can make debugging much
faster and easier.
Take the following steps to take advantage of this feature:
- Place a file called refresh.txt in your Product's source directory
(for example, Products/MyProductName inside your Zope
installation). This file tells Zope to allow refresh for this product.
- Open the Zope Management Interface.
- Expand the Control Panel and Products tabs on the upper left.
- Click on your product.
- Select the Refresh tab.
- Check the "Auto refresh mode" check box and press "Change".
- Make an edit to your product source, and you should see
the changes you made take effect in the next browser page load.
Limitations: Zope may not refresh code if you use import statements
within functions or methods. Also, code that manages to retain references to
old code objects after a refresh (for example, by holding the references in a
C/C++ extension module) will not perform as expected.
If you do run into a case where auto-reload causes problems, you will
need to restart Zope from the Zope Management Interface's Control Panel
or from the command line. Note that pressing the Stop button in Wing
only disconnects from the debug process and does not terminate Zope.
Alternative Approach to Reloading
The refresh.txt techique for module reloading is discouraged in the Plone
community. Another option for reloading both Zope and Plone filesystem-based
code is plone.reload available from pypi at http://pypi.python.org/pypi/plone.reload. plone.reload will allow you
to reload Python code that has been changed since the last reload, and also
give you the option to reload any zcml configuration changes.
If you are using buildout, add plone.reload to the eggs and zcml
sections of your buildout.cfg and re-run buildout.
To use plone.reload, assuming Zope is running on your local machine at
port 8080, log into the ZMI as a Manager user, then go to
http://localhost:8080/@@reload on your
Zope instance with a web browser (append @@reload to the Zope instance
root, not your Plone site if you are using Plone).
Notes:
- If you are using Plone, your Plone product's profile config files (*.xml files)
get loaded through the ZMI at /YourPlone/portal_setup in the import tab.
- Code that uses a @decorator will still likely require a restart.
Setting up Remote Debugging
Configuring Wing for remote debugging can be complicated, so we
recommend using X Windows (Linux/Unix) or Remote Desktop (Windows)
to run Wing IDE on the same machine as Zope but display it remotely.
When this is not possible, you can set up Wing to debug Zope running
on another machine, as described below:
- Set up File Sharing -- You will need some mechanism for
sharing files between the Zope host and the Wing IDE host. Windows file
sharing, Samba, NFS, and ftp or rsync mirroring are all options.
For secure file sharing via SSH on Linux, try sshfs.
- Install Wing on the Server -- You will also need to install Wing on
the host where Zope is running, if it is not already there. No
license is needed for this installation, unless you plan to also
run the IDE there. If there is no binary distribution of Wing available for the
operating system where Zope is running, you can instead install only
the debugger libraries by building them from source code (contact Wingware
for details).
- Basic Configuration -- Follow the instructions for Single-Host
Debugging above first if you have not already done so. Then return here
for additional setup instructions.
- Configure Allowed Hosts -- You will need to add the IP address of
the Zope host to the Allowed Hosts preference in Wing. Otherwise
Wing will not accept your debug connections.
- Configure File Mapping -- Next, set up a mapping between the location
of the Zope installation on your Zope host and the point where it is
accessible on you Wing IDE host. For example, if your Zope host is 192.168.1.1 Zope is installed in
/home/myuser/Zope on that machine, and /home/myuser is mounted on your
Wing IDE host as e:, you would add a Location Map preference setting
that maps 192.168.1.1 to a list containing /home/myuser/Zope and e:/Zope.
For more information on this, see File Location Maps and Location Map Examples
in the Wing IDE manual.
- Set the Zope Host -- Go into Project Properties and set the Zope Host
to match the host name used in configuring the File Location Map in the previous
step. This is used to identify which host mapping should be applied to
file names read from the zope.conf file.
- Modify WingDBG Configuration -- When debugging remotely, the value
given to WingDBG for the Wing Home Directory must be the location
where Wing is installed on the Zope host (the default value will
usually need to be changed).
- Check Project Configuration -- Similarly, the paths identified
in Project Properties should be those on the host where Wing
IDE is running, not the paths on the Zope host.
Trouble Shooting Guide
You can obtain additional verbose output from Wing IDE and the debug
process as follows:
- If Zope or Plone on Windows is yielding a Site Error page with a notFoundError
when run under Wing's debugger, you may need to go into the Zope Management
Interface and delete the access rule (... accessRule.py ...). Now, Zope/Plone runs
on port 8080, does not alter the configuration of port 80, and will work properly
with Wing's debug port (50080 by default). If the URL for your front page
is http://localhost:8080/default/front-page, the Wing IDE debug url will always
be the same but with the different port: http://localhost:50080/default/front-page
(Thanks for Joel Burton for this tip!)
- Go into the Wing Debugging Service in the Zope Management Interface and set Log
file under the Configure tab. Using <stdout> will cause
logging information to be printed to the console from which Zope was
started. Alternatively, set this to the full path of a log file. This file must already
exist for logging to occur.
- Restart Zope and Wing and try to initiate debug.
- Inspect the contents of the log. If you are running Zope and Wing IDE on two
separate hosts, you should also inspect the error-log file on the Wing IDE
host (located in the User Settings Directory). It contains additional
logging information from the Wing IDE process.
For additional help, send these errors logs to support at wingware.com.