<type>how-to</type>
<domain>install</domain>
<id>zope</id>
<title>Using Wing with Zope</title>
<date>$Date$</date>
<product>per+</product>
<summary>Learn how Wing can be used to develop and debug Python code running under Zope2 and Zope4.</summary>

.. note::
  **"The best solution for debugging Zope and Plone"**
  *-- Joel Burton, Member, Plone Team*

.. image:: /images/screenshots/wing7-screenshot-linen.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code written for Zope.

Two versions of Wing are appropriate for use with this document: Wing Pro is the
full-featured Python IDE for professional developers, and Wing Personal is a free
alternative with reduced feature set.

If you do not already have Wing installed, `download it now <https://wingware.com/downloads>`__.

This document describes how to configure Wing for Zope. To get started using Wing as your
Python IDE, please refer to the tutorial in Wing's ``Help`` menu or read the `Quickstart
Guide <ref:howtos/quickstart>`__.

**Note:** This document is not being maintained and was last tested with Zope2. 

If you are using Plone, see also `Using Wing with Plone <ref:howtos/plone>`__. If you are
using Zope3, now known as BlueBream, see `Debugging Externally Launched Code
<ref:debug/debugging-externally-launched-code>`__ or try `z3wingdbg
<http://www.zopatista.com/projects/z3wingdbg>`__ by Martijn Pieters.

**Limitations:** Wing cannot debug DTML, Page Templates, ZCML, or Python code that is not
stored on the file system.

Quick Start on a Single Host
----------------------------

To use Wing with Zope running on the same host as the IDE:

* **Install Zope** -- You can obtain Zope from `zope.org <http://www.zope.org>`__.

* **Install Wing** -- Download and install `Wing <https://wingware.com/downloads>`__.
  See `Installing <ref:install/installing>`__ for details.
  
* **Configure Wing** -- 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
  <script:view_project_properties#highlighted_attrib="proj.zope-support">`__ and to specify
  the `Zope2 Instance Home
  <script:view_project_properties#highlighted_attrib="proj.zope-instance-dir">`__ 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 entry point 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 Entry Point`` 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 <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
---------------

Once you've started the debugger successfully, here are some things
to try:

**Run to a Breakpoint** -- Open up your Zope code in Wing 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 Console`` (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'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
<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 <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 X11 (Linux/Unix) or Remote Desktop (Windows)
to run Wing 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 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  `Debugger > Advanced > 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 your Wing 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 host as ``e:``, you would add a `Debugger > Advanced > 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 `Manually Configured File Location Maps`__ and `Location Map Examples`__
  in the Wing 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.

__ http://fuse.sourceforge.net/sshfs.html
__ script:show_preferences_gui#prefname="debug.passive-hosts"
__ script:show_preferences_gui#prefname="debug.location-map"
__ ref:debug/file-location-maps
__ ref:debug/file-location-map-example

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.

Trouble Shooting Guide
----------------------

You can obtain additional verbose output from Wing 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 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 on two separate hosts,
  you should also inspect the ``ide.log`` file on the Wing host (located in the `Settings
  Directory <ref:install/user-settings-dir>`__). It contains additional logging information
  from the Wing process.

For additional help, send these errors logs to `support at wingware.com
<mailto:support@wingware.com>`__.

Related Documents
-----------------

For more information see:

* `Zope home page <http://www.zope.org>`__ contains much additional information for Zope
  programmers.

* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing's features.

* `Wing Reference Manual <ref:manual>`__ documents Wing in detail.
