Show
Ignore:
Timestamp:
07/31/07 10:09:19 (5 years ago)
Author:
mj
Message:

Merge Wing 3b1 changes.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • WingDBG/trunk/documentation/wingdbgdocs.html

    r87 r358  
    1010<body> 
    1111<div class="document"> 
     12<div class="note"> 
     13<p class="first admonition-title">Note</p> 
     14<p class="last"><strong>&quot;The best solution for debugging Zope and Plone&quot;</strong> 
     15<em>-- Joel Burton, Member, Plone Team, Jul 2005</em></p> 
     16</div> 
    1217<p><a class="reference" href="http://wingware.com/wingide">Wing IDE</a> can be used to develop and debug Python code running under 
    13 Zope2, including Products, External Methods, file system-based Scripts 
     18Zope2 or Zope3, including Products, External Methods, file system-based Scripts 
    1419and Zope itself. It is also useful for Zope-based frameworks like 
    1520<a class="reference" href="http://www.plone.org/">Plone</a> (see <a class="reference" href="http://wingware.com/doc/howtos/plone">Plone Quickstart</a>).</p> 
    … …  
    1823with Zope's code reloading features to achieve a very short edit/debug 
    1924cycle.</p> 
    20 <p><strong>Limitations:</strong> Wing IDE cannot debug DTML or Python code that is not 
    21 stored on the file system.</p> 
     25<div class="note"> 
     26<p class="first admonition-title">Note</p> 
     27<p><strong>Note:</strong> This guide is for Zope2 users.  If you are using Zope3, please 
     28try <a class="reference" href="http://www.zopatista.com/projects/z3wingdbg">z3wingdbg</a> by Martijn Pieters or refer to <a class="reference" href="http://wingware.com/doc/debug/debugging-externally-launched-code">Debugging Externally  
     29Launched Code</a> in the users manual top set up Zope3 debugging manually.</p> 
     30</div> 
     31<p><strong>Limitations:</strong> Wing IDE cannot debug DTML, Page Templates, ZCML, 
     32or Python code that is not stored on the file system.</p> 
    2233<p><strong>Security Warning:</strong> We advise against using the WingDBG product 
    2334on production web servers.  Any user connected to the Wing IDE debugger 
    2435will (unavoidably) have extensive access to files and data on the system.</p> 
    25 <div class="note"> 
    26 <p class="first admonition-title">Note</p> 
    27 <p><strong>Note:</strong> This guide is for Zope2 users.  If you are using Zope3, please 
    28 refer to <a class="reference" href="http://wingware.com/doc/debug/debugging-externally-launched-code">Debugging Externally Launched Code</a> in the users manual.</p> 
    29 </div> 
    3036<div class="section" id="quick-start-on-a-single-host"> 
    3137<h1><a name="quick-start-on-a-single-host">Quick Start on a Single Host</a></h1> 
    3238<p>To use Wing IDE with Zope running on the same host as the IDE:</p> 
    33 <ul> 
    34 <li><p class="first"><strong>Install Zope</strong> -- You can obtain Zope from <a class="reference" href="http://www.zope.org">zope.org</a>.  Version  
    35 2.5.1 or newer will work with Wing.</p> 
    36 </li> 
    37 <li><p class="first"><strong>Install Wing IDE</strong> -- You will need <a class="reference" href="http://wingware.com/downloads">Wing IDE</a> 2.0.2 or later. 
    38 See <a class="reference" href="http://wingware.com/doc/install/installing">Installing</a> for details.</p> 
    39 </li> 
    40 <li><p class="first"><strong>Configure Wing IDE</strong> -- Start Wing, create or open the project you 
     39<ul class="simple"> 
     40<li><strong>Install Zope</strong> -- You can obtain Zope from <a class="reference" href="http://www.zope.org">zope.org</a>.  Version  
     412.5.1 or newer will work with Wing.</li> 
     42<li><strong>Install Wing IDE</strong> -- You will need <a class="reference" href="http://wingware.com/downloads">Wing IDE</a> 2.1 or later. 
     43See <a class="reference" href="http://wingware.com/doc/install/installing">Installing</a> for details.</li> 
     44<li><strong>Configure Wing IDE</strong> -- Start Wing, create or open the project you 
    4145wish to use (from the <tt class="docutils literal"><span class="pre">Project</span></tt> menu). Then use the <tt class="docutils literal"><span class="pre">Extensions</span></tt> 
    4246tab in <tt class="docutils literal"><span class="pre">Project</span> <span class="pre">Properties</span></tt> to enable <tt class="literal"><span class="pre">Zope2/Plone support</span></tt> and to 
    4347specify the <tt class="literal"><span class="pre">Zope2 Instance Home</span></tt> to use with the project.  Wing 
    4448will find your Zope installation by reading the file <tt class="docutils literal"><span class="pre">etc/zope.conf</span></tt> 
    45 in the provided Zope instance.</p> 
    46 <p>Once you press <tt class="docutils literal"><span class="pre">Apply</span></tt> or <tt class="docutils literal"><span class="pre">OK</span></tt> in the Project Properties 
    47 dialog, Wing will ask to install the WingDBG product and will 
    48 offer to add files from your Zope installation to the project.</p> 
    49 </li> 
    50 <li><p class="first"><strong>Configure the WingDBG Product</strong> -- Start or restart Zope and 
     49in the provided Zope instance.  Once you press <tt class="docutils literal"><span class="pre">Apply</span></tt> or <tt class="docutils literal"><span class="pre">OK</span></tt> in the Project  
     50Properties dialog, Wing will ask to install the WingDBG product and will 
     51offer to add files from your Zope installation to the project.</li> 
     52<li><strong>Configure the WingDBG Product</strong> -- Start or restart Zope and 
    5153log into <a class="reference" href="http://localhost:8080/manage">http://localhost:8080/manage</a> (assuming default Zope 
    5254configuration).  The Wing Debugging Service will be created automatically 
    53 on startup; you can find it under the Control Panel of your server.</p> 
    54 </li> 
     55on startup; you can find it under the Control Panel of your server.</li> 
    5556</ul> 
    5657</div> 
    … …  
    6061selecting the 'Wing Debugging Service'. Click in the &quot;Start&quot; button. The Wing 
    6162IDE status area should display &quot;Debugger: Debug process running&quot;.</p> 
     63<p>Note that you can configure WingDBG to start and connect to the IDE automatically 
     64when Zope is started from the Advanced configuration tab.</p> 
    6265<p><strong>Problems?</strong>  See the Trouble-Shooting Guide below.</p> 
    6366</div> 
    … …  
    142145<p>When this is not possible, you can set up Wing to debug Zope running 
    143146on another machine, as described below:</p> 
    144 <ul> 
    145 <li><p class="first"><strong>Set up File Sharing</strong> -- You will need some mechanism for 
     147<ul class="simple"> 
     148<li><strong>Set up File Sharing</strong> -- You will need some mechanism for 
    146149sharing files between the Zope host and the Wing IDE host. Windows file 
    147150sharing, Samba, NFS, and ftp or rsync mirroring are all options. 
    148 For secure file sharing via SSH on Linux, try <a class="reference" href="http://fuse.sourceforge.net/sshfs.html">sshfs</a>.</p> 
    149 </li> 
    150 <li><p class="first"><strong>Install Wing on Server</strong> -- You will also need to install Wing on 
     151For secure file sharing via SSH on Linux, try <a class="reference" href="http://fuse.sourceforge.net/sshfs.html">sshfs</a>.</li> 
     152<li><strong>Install Wing on Server</strong> -- You will also need to install Wing on 
    151153the host where Zope is running, if it is not already there.  No 
    152154license is needed for this installation, unless you plan to also 
    153 run the IDE there.</p> 
    154 <p>If there is no binary distribution of Wing available for the 
     155run the IDE there. If there is no binary distribution of Wing available for the 
    155156operating system where Zope is running, you can instead install only 
    156157the debugger libraries as outlined in <a class="reference" href="http://wingware.com/doc/howtos/compiling-debugger-sources">Compiling the Wing IDE 
    157 Debugger from Source</a>.</p> 
    158 </li> 
    159 <li><p class="first"><strong>Basic Configuration</strong> -- Follow the instructions for Single-Host 
     158Debugger from Source</a>.</li> 
     159<li><strong>Basic Configuration</strong> -- Follow the instructions for Single-Host 
    160160Debugging above first if you have not already done so. Then return here 
    161 for additional setup instructions.</p> 
    162 </li> 
    163 <li><p class="first"><strong>Configure Allowed Hosts</strong> -- You will need to add the IP address of  
     161for additional setup instructions.</li> 
     162<li><strong>Configure Allowed Hosts</strong> -- You will need to add the IP address of  
    164163the Zope host to the  <tt class="literal"><span class="pre">Allowed Hosts</span></tt> preference in Wing.  Otherwise 
    165 Wing will not accept your debug connections.</p> 
    166 </li> 
    167 <li><p class="first"><strong>Configure File Mapping</strong> -- Next, set up a mapping between the location  
     164Wing will not accept your debug connections.</li> 
     165<li><strong>Configure File Mapping</strong> -- Next, set up a mapping between the location  
    168166of the Zope installation on your Zope host and the point where it is  
    169 accessible on you Wing IDE host.</p> 
    170 <p>For example, if your Zope host is <tt class="docutils literal"><span class="pre">192.168.1.1</span></tt> Zope is installed in 
     167accessible on you Wing IDE host. For example, if your Zope host is <tt class="docutils literal"><span class="pre">192.168.1.1</span></tt> Zope is installed in 
    171168<tt class="docutils literal"><span class="pre">/home/myuser/Zope</span></tt> on that machine, and <tt class="docutils literal"><span class="pre">/home/myuser</span></tt> is mounted on your 
    172169Wing IDE host as <tt class="docutils literal"><span class="pre">e:</span></tt>, you would add a <tt class="literal"><span class="pre">Location Map</span></tt> preference setting 
    173 that maps <tt class="docutils literal"><span class="pre">192.168.1.1</span></tt> to a list containing <tt class="docutils literal"><span class="pre">/home/myuser/Zope</span></tt> and <tt class="docutils literal"><span class="pre">file:e:/Zope</span></tt>.</p> 
    174 <p>For more information on this, see <a class="reference" href="http://wingware.com/doc/debug/file-location-maps">File Location Maps</a> and <a class="reference" href="http://wingware.com/doc/debug/file-location-map-example">Location Map Examples</a> 
    175 in the Wing IDE manual.</p> 
    176 </li> 
    177 <li><p class="first"><strong>Modify WingDBG Configuration</strong> -- When debugging remotely, the value 
     170that maps <tt class="docutils literal"><span class="pre">192.168.1.1</span></tt> to a list containing <tt class="docutils literal"><span class="pre">/home/myuser/Zope</span></tt> and <tt class="docutils literal"><span class="pre">file:e:/Zope</span></tt>. 
     171For more information on this, see <a class="reference" href="http://wingware.com/doc/debug/file-location-maps">File Location Maps</a> and <a class="reference" href="http://wingware.com/doc/debug/file-location-map-example">Location Map Examples</a> 
     172in the Wing IDE manual.</li> 
     173<li><strong>Modify WingDBG Configuration</strong> -- When debugging remotely, the value 
    178174given to WingDBG for the Wing Home Directory must be the location 
    179175where Wing is installed on the Zope host (the default value will 
    180 usually need to be changed).</p> 
    181 </li> 
    182 <li><p class="first"><strong>Check Project Configuration</strong> -- Similarly, the paths identified 
     176usually need to be changed).</li> 
     177<li><strong>Check Project Configuration</strong> -- Similarly, the paths identified 
    183178in Project Properties should be those on the host where Wing 
    184 IDE is running, not the paths on the Zope host.</p> 
    185 </li> 
     179IDE is running, not the paths on the Zope host.</li> 
    186180</ul> 
    187181</div> 
    … …  
    190184<p>You can obtain additional verbose output from Wing IDE and the debug 
    191185process as follows:</p> 
    192 <ul> 
    193 <li><p class="first">Go into the Wing Debugging Service in the Zope Management Interface and set <tt class="docutils literal"><span class="pre">Log</span> 
     186<ul class="simple"> 
     187<li>If Zope or Plone on Windows is yielding a Site Error page with a notFoundError 
     188when run under Wing's debugger, you may need to go into the Zope Management 
     189Interface and delete the access rule (... accessRule.py ...).  Now, Zope/Plone runs 
     190on port 8080, does not alter the configuration of port 80, and will work properly 
     191with Wing's debug port (50080 by default).  If the URL for your front page  
     192is <a class="reference" href="http://localhost:8080/default/front-page">http://localhost:8080/default/front-page</a>, the Wing IDE debug url will always 
     193be the same but with the different port: <a class="reference" href="http://localhost:50080/default/front-page">http://localhost:50080/default/front-page</a> 
     194(Thanks for Joel Burton for this tip!)</li> 
     195<li>Go into the Wing Debugging Service in the Zope Management Interface and set <tt class="docutils literal"><span class="pre">Log</span> 
    194196<span class="pre">file</span></tt> under the <tt class="docutils literal"><span class="pre">Configure</span></tt> tab. Using <tt class="docutils literal"><span class="pre">&lt;stdout&gt;</span></tt> will cause 
    195197logging information to be printed to the console from which Zope was 
    196 started.</p> 
    197 <p>Alternatively, set this to the full path of a log file. This file must already 
    198 exist for logging to occur.</p> 
    199 </li> 
    200 <li><p class="first">Restart Zope and Wing and try to initiate debug.</p> 
    201 </li> 
    202 <li><p class="first">Inspect the contents of the log. If you are running Zope and Wing IDE on two 
     198started.  Alternatively, set this to the full path of a log file. This file must already 
     199exist for logging to occur.</li> 
     200<li>Restart Zope and Wing and try to initiate debug.</li> 
     201<li>Inspect the contents of the log. If you are running Zope and Wing IDE on two 
    203202separate hosts, you should also inspect the <tt class="docutils literal"><span class="pre">error-log</span></tt> file on the Wing IDE 
    204203host (located in the <a class="reference" href="http://wingware.com/doc/install/user-settings-dir">User Settings Directory</a>). It contains additional 
    205 logging information from the Wing IDE process.</p> 
    206 </li> 
     204logging information from the Wing IDE process.</li> 
    207205</ul> 
    208206<p>For additional help, send these errors logs to <a class="reference" href="mailto:support&#64;wingware.com">support at wingware.com</a>.</p>