net.sourceforge.phpeclipse.help/docbook-src/guide/src/en/user-manual/debug_php.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- jEdit buffer-local properties: -->
   3 <!-- :indentSize=2:noTabs=true: -->
   4 <!-- :xml.root=docmaster.xml: -->
   5
   6 <sect1 id="sec.debug_php">
   7   <title>PHP Source Level Debugging</title>
   8   <para>
   9     Besides the method of outputting runtime information by adding <function>echo</function> or <function>var_dump</function> functions to your code, the more sophisticated and convenient method is using a so called <quote>Source Level Debugger</quote>.
  10   </para>
  11
  12   <para>
  13     With the current release of &phpeclipse; only <application>DBG</application> is supported. <application>XDebug</application> is currently supported only by directly checking out from the &phpeclipse; CVS repository and setting it up appropriately (see <xref linkend="sec.install_xdebug"/>).
  14   </para>
  15
  16   <para>
  17     In case you havn't already installed DBG, see <xref linkend="sec.install_dbg"/>. When you are sure the DBG module is correctly installed, you can go forward.
  18   </para>
  19
  20   <para>
  21     To do debugging in &phpeclipse; you need to set up a so called <quote>Debug Configuration</quote>. The following sections describe how to set up such a <quote>Debug Configuration</quote> and how to start a debug session.
  22   </para>
  23
  24   <sect2 id="sec.debug_php_conf">
  25     <title>Setting up a Debug Configuration</title>
  26     <para>
  27       To set up a <quote>Debug Configuration</quote> click on
  28       <menuchoice>
  29         <guimenu>Run</guimenu>
  30         <guisubmenu>Debug...</guisubmenu>
  31       </menuchoice> (see <xref linkend="fig.debug_config_1"/>. Within the opened dialog click on <quote>PHP DBG Script</quote> and click on <guibutton>New</guibutton> (see <xref linkend="fig.debug_config_2"/>). This opens the <quote>Create, manage, and run configuration</quote> dialog.
  32     </para>
  33
  34     <note>
  35       <para>
  36         The first time you open the configuration dialog, you will see an error message within this dialog, complaining about a missing interpreter setting. For entering the interpreter see <xref linkend="sec.debug_php_env_int"/>.
  37       </para>
  38     </note>
  39
  40     <figure id="fig.debug_config_1">
  41       <title>Open the Debug Configuration dialog</title>
  42       <mediaobject>
  43         <imageobject role="html">
  44           <imagedata align="center" fileref="img/en/xo-002/debug_config_1.png" format="PNG"/>
  45         </imageobject>
  46         <imageobject role="fo">
  47           <imagedata align="center" fileref="img/en/xo-002/debug_config_1.png" format="PNG" width="6cm"/>
  48         </imageobject>
  49       </mediaobject>
  50     </figure>
  51
  52     <figure id="fig.debug_config_2">
  53       <title>Debug Configuration with the <quote>Perspectives</quote> view</title>
  54       <mediaobject>
  55         <imageobject role="html">
  56           <imagedata align="center" fileref="img/en/xo-002/debug_config_2.png" format="PNG"/>
  57         </imageobject>
  58         <imageobject role="fo">
  59           <imagedata align="center" fileref="img/en/xo-002/debug_config_2.png" format="PNG" width="12cm"/>
  60         </imageobject>
  61       </mediaobject>
  62     </figure>
  63
  64
  65     <sect3 id="sec.debug_php_conf_name">
  66       <title>Name the Debug Configuration</title>
  67       <para>
  68         Within the <quote>Name:</quote> text field you should change the name (which is <quote>New_configuration</quote> per default) to a more reasonable one (see <xref linkend="fig.debug_config_3"/>).
  69       </para>
  70     </sect3>
  71
  72
  73     <sect3 id="sec.debug_php_conf_file">
  74       <title>Configure File</title>
  75       <para>
  76         Within the <quote>File</quote> tab you find two entries:
  77         <itemizedlist>
  78           <listitem>
  79             <para>
  80               <emphasis role="bold">Project:</emphasis> This is the project this debug configuration belongs to.
  81             </para>
  82           </listitem>
  83           <listitem>
  84             <para>
  85               <emphasis role="bold">File:</emphasis> This is used for <quote>Non Remote Debugging</quote>. The given file is directly given the interpreter which is entered within the Interpreter tab (see <xref linkend="sec.debug_php_env_int"/>). And/or is it called when configured for using the internal browser.
  86             </para>
  87           </listitem>
  88         </itemizedlist>
  89       </para>
  90
  91       <figure id="fig.debug_config_3">
  92         <title>Set up Debug Configuration - File</title>
  93         <mediaobject>
  94           <imageobject role="html">
  95             <imagedata align="center" fileref="img/en/xo-002/debug_config_3.png" format="PNG"/>
  96           </imageobject>
  97           <imageobject role="fo">
  98             <imagedata align="center" fileref="img/en/xo-002/debug_config_3.png" format="PNG" width="12cm"/>
  99           </imageobject>
 100         </mediaobject>
 101       </figure>
 102     </sect3>
 103
 104
 105     <sect3 id="sec.debug_php_arg">
 106       <title>Configure Arguments</title>
 107       <para>
 108         These settings are used for <quote>Non Remote Debugging</quote>. If the given Interpreter is directly called by &phpeclipse; (see <xref linkend="sec.debug_cli"/>).
 109       </para>
 110
 111       <itemizedlist>
 112         <listitem>
 113           <para>
 114             <emphasis role="bold">Working Directory</emphasis>:
 115           </para>
 116         </listitem>
 117         <listitem>
 118           <para>
 119             <emphasis role="bold">Use default working directory</emphasis>:
 120           </para>
 121         </listitem>
 122         <listitem id="sec.debug_php_arg.li.int_args">
 123           <para>
 124             <emphasis role="bold">Interpreter Arguments</emphasis>: Here you can specify the arguments which will passed to the interpreter (see <ulink url="http://de3.php.net/manual/en/features.commandline.php">Using PHP from the command line</ulink>).
 125           </para>
 126         </listitem>
 127         <listitem>
 128           <para>
 129             <emphasis role="bold">Program Arguments</emphasis>: Here you can specify the arguments which will be passed to your script, and can be accessed by the <varname>$argv[]</varname> - array.
 130           </para>
 131         </listitem>
 132       </itemizedlist>
 133     </sect3>
 134
 135
 136     <sect3 id="sec.debug_php_env">
 137       <title>Configure Environment</title>
 138       <para>
 139         Within this tab you have to enter the most important settings for a successful debugging session.
 140       </para>
 141
 142
 143       <sect4 id="sec.debug_php_env_int">
 144         <title>Configure Environment Interpreter</title>
 145         <para>
 146           Although the setting of the interpreter isn't really necessary for <quote>Remote Debugging</quote>, you have to set it up. For a default XAMPP installation this would be <filename>C:\Program Files\apachefriends\xampp\php\php.exe</filename>.
 147         </para>
 148
 149         <para>
 150           The interpreter is used when you set a <quote>Debug Configuration</quote> with <quote>Remote Debug</quote> deactivated. This is true if you want to debug a script which is started per php cli.
 151         </para>
 152       </sect4>
 153
 154
 155       <sect4 id="sec.debug_php_env_remote">
 156         <title>Configure Environment Remote Debug</title>
 157         <para>
 158           Here can you have up to five options to enter:
 159           <itemizedlist>
 160             <listitem>
 161               <para>
 162                 <emphasis role="bold">Remote Debug</emphasis>: You activate this if you want to debug a script which is started from an external browser (this is in opposite of the usage of the browser which is build into &phpeclipse;). When you disable this checkbox the appropriate script is forwarded directly to the given interpreter (php.exe)
 163               </para>
 164             </listitem>
 165             <listitem>
 166               <para>
 167                 <emphasis role="bold">Cross Platform debugging</emphasis>: Originally used for converting the path seperator (which are different on *nix and Windows systems). As far as I can remember this isn't necessary anymore.
 168               </para>
 169             </listitem>
 170             <listitem>
 171               <para>
 172                 <emphasis role="bold">Open with DBGSession URL in internal Browser</emphasis>: Activate this if you don't want to use the an external browser but start a debug session in internal browser.
 173               </para>
 174             </listitem>
 175             <listitem>
 176               <para>
 177                 <emphasis role="bold">Remote Sourcepath</emphasis>: An incorrect setting of this path information is responsible for the most annoyances in respect of debugging problems. The <quote>Remote Sourcepath</quote> is important because it is used for translating the path informations which are exchanged between &phpeclipse; and DBG. So, if this translation is incorrect, &phpeclipse; will not find the correct file when a break occurs, nor will DBG know for which file it should set a breakpoint. More different and detailed examples are to come:
 178               </para>
 179             </listitem>
 180             <listitem>
 181               <para>
 182                 <emphasis role="bold">Mapped Path</emphasis>: Although in most cases a single path mapping is sufficient, but there are situations where this isn't enough. This is when you use PHP files (e.g. phplib) which are located on a total different path. To use this option, it is necessary to leave the <quote>Remote Sourcepath</quote> field empty. More different and detailed examples are to come:
 183               </para>
 184             </listitem>
 185           </itemizedlist>
 186         </para>
 187       </sect4>
 188     </sect3>
 189
 190
 191     <sect3 id="sec.debug_php_env_var">
 192       <title>Configure Environment Variables</title>
 193       <para>
 194         Used within <quote>Non Remote Debugging</quote>. You can specify variable - value pairs which are passed to the script within the <varname>$_ENV</varname> and the <varname>$HTTP_ENV_VARS</varname> array.
 195       </para>
 196     </sect3>
 197
 198
 199     <sect3 id="sec.debug_php_common">
 200       <title>Configure Common</title>
 201       <para>
 202         Leave all as it is per default. <!-- todo: what are they for? -->
 203       </para>
 204     </sect3>
 205
 206     <sect3 id="sec.debug_php_apply">
 207       <title>Save Configuration</title>
 208       <para>
 209         When you have done all the necessary settings click on <guibutton>Apply</guibutton> to save the configuration. You can recall this configuration by clicking on the name of the desired configuration in the <quote>Configurations pane</quote> on the left side.
 210       </para>
 211     </sect3>
 212
 213     <sect3 id="sec.debug_php_start">
 214       <title>Start a Debug Configuration</title>
 215       <para>
 216         You can start a <quote>Debug Configuration</quote> at once within the configuration dialog via the <guibutton>Debug</guibutton>.
 217       </para>
 218       <para>
 219
 220       </para>
 221     </sect3>
 222   </sect2>
 223
 224   <sect2 id="sec.debug_remote">
 225     <title>Remote Debugging</title>
 226     <para>
 227       It is called <quote>Remote Debugging</quote> if you want to debug php scripts which are started by web server. This is the case if you are doing so called <quote>Web Devolepment</quote>. In opposite you also can write php scripts and start them from a shell or command line (see <xref linkend="sec.debug_cli" />).
 228     </para>
 229
 230     <para>
 231
 232     </para>
 233
 234   </sect2>
 235
 236
 237   <sect2 id="sec.debug_cli">
 238     <title>Debugging CLI</title>
 239     <para>
 240       In contrary to <quote>Remote Debugging</quote> where your php scripts are started by a web server, you could also write scripts and start them from command line<footnote><para>cli stands for <quote>Command Line Interface</quote></para></footnote>. For that task you have to deactivate the <quote>Remote Debug</quote> checkbox (see <xref linkend="sec.debug_php_env_remote" />), and set the appropriate php cli application. According the PHP version you use, this is:
 241       <itemizedlist>
 242         <listitem>
 243           <para>
 244             phpcli.exe for PHP 4
 245           </para>
 246         </listitem>
 247         <listitem>
 248           <para>
 249             php-win.exe for PHP 5
 250           </para>
 251         </listitem>
 252       </itemizedlist>
 253     </para>
 254
 255     <para>
 256       The prerequiste for debugging is also that you have installed &dbg; as it is described in <xref linkend="sec.install_dbg"/>. In addition, for the breakpoints to work, you have to add the following line to the <quote>[debugger]</quote> section of your <filename>php.ini</filename>:
 257       <programlisting><![CDATA[debugger.JIT_enabled=on]]></programlisting>
 258       And also you need the following code at the top of your php file you want to debug. At least this code snippet should be located before the first breakpoint you want to set.
 259       <programlisting><![CDATA[if (function_exists ("DebugBreak")) {
 260   DebugBreak ();
 261 }]]></programlisting>
 262     </para>
 263
 264     <note>
 265       <para>
 266         For debugging a php-cli script you need the appropriate &phpeclipse; version, which is &gt; phpeclipse-1.1.9-cvs-20060424. This is due to the fact that older &phpeclipse; versions listen on port 10001, but dbg uses the standard port 7869, and there is no way to submit a different port neither by cli nor through the <filename>php.ini</filename><footnote><para>This is true for the free &dbg; version.</para></footnote>.
 267       </para>
 268     </note>
 269
 270     <tip>
 271       <para>
 272         If you don't want to change the <filename>php.ini</filename> which you also do use for your web scripts, you can <quote>import</quote> the appropriate <filename>php.ini</filename> to your project, and modify this project related local copy of the <filename>php.ini</filename> file. To use this local <filename>php.ini</filename> set the <quote>Interpreter Argument</quote> (see <xref linkend="sec.debug_php_arg"/>) as follows:
 273         <quote>-c your_project_name/php.ini</quote>.
 274       </para>
 275     </tip>
 276   </sect2>
 277
 278   <sect2 id="sec.debug_scenarios">
 279     <title>Debug Scenarios</title>
 280     <para>
 281       One of the most important configuration point which is responsible for successfully debugging your PHP code is the correct setting of the <quote>Remote Sourcepath</quote>. Without a correct setting, you wan't be able to run a debugging session. As the setting of the &remso; is dependent of your working environment, we will first explain why it is needed and how it works and then, we will provide some examples.
 282     </para>
 283
 284     <sect3 id="sec.debug_scenarios_remote_sourcepath">
 285       <title>How the &remso; works</title>
 286       <para>
 287         Why do we need a &remso; setting? All files are defined by the path relative to the current &eclipse; workspace and project. E.g our workspace is <filename>C:\Document and Settings\Robert\workspace</filename>. Within this workspace we have a PHP project called <filename>MyPHPProject</filename> and a file <filename>MyPHPFile.php</filename>. From &dbg; this file would be reported as <filename>C:\Document and Settings\Robert\workspace\MyPHPProject\MyPHPFile.php</filename>. The &remso; is now used to remove the full path, so we get a file with a relative path, which would be in this case the filename itself.
 288       </para>
 289
 290       <para>
 291         In this example the &remso; setting would be <filename>C:\Document and Settings\Robert\workspace\MyPHPProject</filename>. This is by the way the default setting of the &remso; when you create a new debug configuration. But this setting is only correct if your the webservers &docroot; is set to exactly this folder.
 292       </para>
 293     </sect3>
 294
 295     <sect3 id="sec.debug_scenario_1">
 296       <title>Same Machine, Workspace is &docroot;</title>
 297       <para>
 298
 299       </para>
 300     </sect3>
 301
 302     <sect3 id="sec.debug_scenario_2">
 303       <title>Same Machine, Workspace and &docroot; is Different</title>
 304       <para>
 305
 306       </para>
 307     </sect3>
 308
 309
 310     <sect3 id="sec.debug_scenario_3">
 311       <title>Different Machine, Workspace and &docroot; is Different</title>
 312       <para>
 313
 314       </para>
 315     </sect3>
 316   </sect2>
 317
 318
 319   <sect2 id="sec.running_debug_session">
 320     <title>Running a Debug Session</title>
 321     <para>
 322       Open Debug perspective. Select a existing debug configuration. Or create a new one. Should see following in Debug View.
 323       Internal Browser or external browser. Submit URL in external browser.
 324
 325     </para>
 326
 327     <sect3 id="sec.running_resume">
 328       <title>Resume</title>
 329       <para>
 330
 331       </para>
 332     </sect3>
 333
 334
 335     <sect3 id="sec.running_suspend">
 336       <title>Suspend</title>
 337       <para>
 338
 339       </para>
 340     </sect3>
 341
 342     <sect3 id="sec.running_terminate">
 343       <title>Terminate</title>
 344       <para>
 345
 346       </para>
 347     </sect3>
 348
 349     <sect3 id="sec.running_step_into">
 350       <title>Step Into</title>
 351       <para>
 352
 353       </para>
 354     </sect3>
 355
 356     <sect3 id="sec.running_step_over">
 357       <title>Step Into</title>
 358       <para>
 359
 360       </para>
 361     </sect3>
 362
 363     <sect3 id="sec.running_step_return">
 364       <title>Step Return</title>
 365       <para>
 366
 367       </para>
 368     </sect3>
 369
 370
 371     <sect3 id="sec.breakpoints">
 372       <title>Breakpoints</title>
 373       <para>
 374
 375       </para>
 376
 377
 378       <figure id="fig.breakpoints_view">
 379         <title>The &bpview;</title>
 380         <mediaobject>
 381           <imageobject role="html">
 382             <imagedata align="center" fileref="img/en/xo-002/breakpoints_view.png" format="PNG"/>
 383           </imageobject>
 384           <imageobject role="fo">
 385             <imagedata align="center" fileref="img/en/xo-002/breakpoints_view.png" format="PNG" width="7cm"/>
 386           </imageobject>
 387         </mediaobject>
 388       </figure>
 389
 390
 391       <figure id="fig.breakpoints_view_context_menu">
 392         <title>The &bpview; context menu</title>
 393         <mediaobject>
 394           <imageobject role="html">
 395             <imagedata align="center" fileref="img/en/xo-002/breakpoints_view_context_menu.png" format="PNG"/>
 396           </imageobject>
 397           <imageobject role="fo">
 398             <imagedata align="center" fileref="img/en/xo-002/breakpoints_view_context_menu.png" format="PNG" width="7cm"/>
 399           </imageobject>
 400         </mediaobject>
 401       </figure>
 402
 403
 404       <figure id="fig.breakpoints_view_icon_bar">
 405         <title>The &bpview; icon bar</title>
 406         <mediaobject>
 407           <imageobject role="html">
 408             <imagedata align="center" fileref="img/en/xo-002/breakpoints_view_icon_bar.png" format="PNG"/>
 409           </imageobject>
 410           <imageobject role="fo">
 411             <imagedata align="center" fileref="img/en/xo-002/breakpoints_view_icon_bar.png" format="PNG" width="7cm"/>
 412           </imageobject>
 413         </mediaobject>
 414       </figure>
 415
 416
 417       <figure id="fig.editor_view_left_ruler_context_menu">
 418         <title>The &editview; left ruler context menu</title>
 419         <mediaobject>
 420           <imageobject role="html">
 421             <imagedata align="center" fileref="img/en/xo-002/editor_view_left_ruler_context_menu.png" format="PNG"/>
 422           </imageobject>
 423           <imageobject role="fo">
 424             <imagedata align="center" fileref="img/en/xo-002/editor_view_left_ruler_context_menu.png" format="PNG" width="7cm"/>
 425           </imageobject>
 426         </mediaobject>
 427       </figure>
 428
 429
 430       <sect4 id="sec.breakpoint_set">
 431         <title>Set Breakpoint</title>
 432         <para>
 433           A breakpoint can be set by the following methods:
 434           <itemizedlist>
 435             <listitem>
 436               <para>
 437                 By double clicking within the left vertical ruler of the editor window
 438               </para>
 439             </listitem>
 440             <listitem>
 441               <para>
 442                 Via the left vertical ruler context menu item <menuchoice><guimenu>Toggle PHP Breakpoint</guimenu></menuchoice> (see <xref linkend="fig.editor_view_left_ruler_context_menu" />)
 443               </para>
 444             </listitem>
 445           </itemizedlist>
 446         </para>
 447       </sect4>
 448
 449
 450       <sect4 id="sec.breakpoint_remove">
 451         <title>Remove Breakpoint</title>
 452         <para>
 453           A breakpoint can be removed by the following methods:
 454           <itemizedlist>
 455             <listitem>
 456               <para>
 457                 By double clicking within the left vertical ruler of the editor window
 458               </para>
 459             </listitem>
 460             <listitem>
 461               <para>
 462                 Via the left vertical ruler context menu item <menuchoice><guimenu>Toggle PHP Breakpoint</guimenu></menuchoice> (see <xref linkend="fig.editor_view_left_ruler_context_menu" />).
 463               </para>
 464             </listitem>
 465             <listitem>
 466               <para>
 467                 Via the &bpview;, by simple typing <keycap>Del</keycap>
 468               </para>
 469             </listitem>
 470             <listitem>
 471               <para>
 472                 Via the &bpview; context menu item <menuchoice><guimenu>Remove</guimenu></menuchoice> (see <xref linkend="fig.breakpoints_view_context_menu"/>)
 473               </para>
 474             </listitem>
 475             <listitem>
 476               <para>
 477                 Via the &bpview; icon bar <quote>Remove</quote> icon (see <xref linkend="fig.breakpoints_view_icon_bar"/>).
 478               </para>
 479             </listitem>
 480           </itemizedlist>
 481         </para>
 482       </sect4>
 483
 484
 485       <sect4 id="sec.breakpoint_enable">
 486         <title>Enable/Disable Breakpoint</title>
 487         <para>
 488           A breakpoint can temporary disabled (and enabled) by the following methods:
 489           <itemizedlist>
 490             <listitem>
 491               <para>
 492                 By clicking into the check box of the appropriate breakpoint within the &bpview; (see <xref linkend="fig.breakpoints_view"/>
 493               </para>
 494             </listitem>
 495             <listitem>
 496               <para>
 497                 Via the &bpview; context menu item <menuchoice><guimenu>Disable</guimenu></menuchoice> (and enabled via <menuchoice><guimenu>Enable</guimenu></menuchoice>) (see <xref linkend="fig.breakpoints_view_context_menu"/>). The context menu commands are related to all selected breakpoints.
 498               </para>
 499             </listitem>
 500           </itemizedlist>
 501         </para>
 502       </sect4>
 503
 504
 505       <sect4 id="sec.breakpoint_conditional">
 506         <title>Conditional Breakpoints</title>
 507         <para>
 508           You can assign a condition to a breakpoint via the &bpview; context menu item <menuchoice><guimenu>Properties</guimenu></menuchoice> (see <xref linkend="fig.breakpoints_view_context_menu"/>). This opens a dialog (see <xref linkend="fig.breakpoint_properties_condition"/>). Within the text field <quote>Break Condition</quote> you can set a condition. Don't forget to activate the conditional break via the check box <quote>Enable Condition</quote> at the bottom of the dialog.
 509         </para>
 510         <para>
 511           For example, if you type <quote>$a == 12</quote> as condition, the program will break if the variable <quote>$a</quote> has the value <quote>12</quote>.
 512         </para>
 513
 514
 515         <figure id="fig.breakpoint_properties_condition">
 516           <title>The breakpoint <quote>Properties</quote> dialog</title>
 517           <mediaobject>
 518             <imageobject role="html">
 519               <imagedata align="center" fileref="img/en/xo-002/breakpoint_properties_conditional.png" format="PNG"/>
 520             </imageobject>
 521             <imageobject role="fo">
 522               <imagedata align="center" fileref="img/en/xo-002/breakpoint_properties_condition.png" format="PNG" width="7cm"/>
 523             </imageobject>
 524           </mediaobject>
 525         </figure>
 526       </sect4>
 527
 528       <sect4 id="sec.breakpoint_skipcount">
 529         <title>Breakpoint Skipcounts</title>
 530         <para>
 531           An additional feature to set for breakpoints is the <quote>Skipcounts</quote> condition. Normally the skipcounts is set to 0, which means the program breaks immediately if it scores a breakpoint. If the <quote>Skiptcounts</quote> is set to 1 it means, that the first score of a breakpoint is ignored (skipped) and the second score will lead to a break of the program.
 532         </para>
 533
 534         <para>
 535           The <quote>Skipcounts</quote> can be set via the same dialog box as the conditional breakpoints (see <xref linkend="sec.breakpoint_conditional"/>). For the <quote>Skipcounts</quote> the checkbox need not to be activated.
 536         </para>
 537
 538         <note>
 539           <para>
 540             The <quote>Break Condition</quote> has precedence over the <quote>Skipcounts</quote>.
 541           </para>
 542         </note>
 543       </sect4>
 544
 545     </sect3>
 546
 547
 548     <sect3 id="sec.variables">
 549       <title>Inspect Variables</title>
 550       <para>
 551         Within the <quote>Variables View</quote> you can see all the variables with their values.
 552       </para>
 553       <para>
 554         To open the <quote>Variables View</quote> within the <quote>Debug Perspective</quote> go to
 555         <menuchoice>
 556           <guimenu>Window</guimenu>
 557           <guisubmenu>Show View</guisubmenu>
 558           <guisubmenu>Variables</guisubmenu>
 559         </menuchoice> (see <xref linkend="fig.variables_view_open"/>).
 560       </para>
 561
 562       <note>
 563         <para>
 564           Be sure that your current perspective is the <quote>Debug Perspective</quote>. Although you can open the <quote>Variable View</quote> within a different perspective, this doesn't make sense.
 565         </para>
 566       </note>
 567
 568
 569       <figure id="fig.variables_view_open">
 570         <title>Open the &varview;</title>
 571         <mediaobject>
 572           <imageobject role="html">
 573             <imagedata align="center" fileref="img/en/xo-002/variables_view_open.png" format="PNG"/>
 574           </imageobject>
 575           <imageobject role="fo">
 576             <imagedata align="center" fileref="img/en/xo-002/variables_view_open.png" format="PNG" width="8cm"/>
 577           </imageobject>
 578         </mediaobject>
 579       </figure>
 580
 581
 582       <figure id="fig.variables_view_context_menu">
 583         <title>The &varview; context menu</title>
 584         <mediaobject>
 585           <imageobject role="html">
 586             <imagedata align="center" fileref="img/en/xo-002/variables_view_context_menu.png" format="PNG"/>
 587           </imageobject>
 588           <imageobject role="fo">
 589             <imagedata align="center" fileref="img/en/xo-002/variables_view_context_menu.png" format="PNG" width="7cm"/>
 590           </imageobject>
 591         </mediaobject>
 592       </figure>
 593
 594     </sect3>
 595
 596
 597     <sect3 id="sec.variable_hover">
 598       <title>Show Variable Value by Hovering</title>
 599       <para>
 600         Besides inspecting the value of a variable by looking into the &varview; or the &expview; a simple and quick method is to position the mouse pointer over the variable within the source code. Within a second the value and type of the variable is shown (see <xref linkend="fig.variables_view_hover"/>).
 601       </para>
 602
 603
 604       <figure id="fig.variables_view_hover">
 605         <title>Show variable value by hovering</title>
 606         <mediaobject>
 607           <imageobject role="html">
 608             <imagedata align="center" fileref="img/en/xo-002/variables_view_hover.png" format="PNG"/>
 609           </imageobject>
 610           <imageobject role="fo">
 611             <imagedata align="center" fileref="img/en/xo-002/variables_view_hover.png" format="PNG" width="6cm"/>
 612           </imageobject>
 613         </mediaobject>
 614       </figure>
 615     </sect3>
 616
 617
 618     <sect3 id="sec.watch_expressions">
 619       <title>Watch Expressions</title>
 620       <para>
 621         Within the &expview; you can see the result of an expression. In the simplest form, this is just a variable and the corresponding value. But of course an expression can also be more complex, e.g. a mathematical formula.
 622       </para>
 623       <para>
 624         There are different ways to open the <quote>Expressions View</quote> and to add an expression.
 625       </para>
 626
 627
 628       <sect4 id="sec.watch_expressions_open_1">
 629         <title>Open &expview; via Main Menu</title>
 630         <para>
 631           To open the &expview; within the <quote>Debug Perspective</quote> go to
 632           <menuchoice>
 633             <guimenu>Window</guimenu>
 634             <guisubmenu>Show View</guisubmenu>
 635             <guisubmenu>Variables</guisubmenu>
 636           </menuchoice> (see <xref linkend="fig.variables_view_open_1"/>).
 637         </para>
 638
 639         <note>
 640           <para>
 641             Be sure that your current perspective is the <quote>Debug Perspective</quote>. Although you can open the &expview; within a different perspective, this doesn't make sense.
 642           </para>
 643         </note>
 644
 645
 646         <figure id="fig.expressions_view_open_1">
 647           <title>Open the &expview; via the main menu</title>
 648           <mediaobject>
 649             <imageobject role="html">
 650               <imagedata align="center" fileref="img/en/xo-002/expressions_view_open_1.png" format="PNG"/>
 651             </imageobject>
 652             <imageobject role="fo">
 653               <imagedata align="center" fileref="img/en/xo-002/expressions_view_open_1.png" format="PNG" width="8cm"/>
 654             </imageobject>
 655           </mediaobject>
 656         </figure>
 657       </sect4>
 658
 659       <sect4 id="sec.watch_expressions_open_2">
 660         <title>Open &expview; via the &varview;</title>
 661         <para>
 662           Right clicking on a variable within the &varview; opens the context menu. Then click on <guimenu>Create Watch Expression</guimenu>. This adds the selected variable to the &expview; and opens/activates the &expview;.
 663
 664           <menuchoice>
 665             <guimenu>Window</guimenu>
 666             <guisubmenu>Show View</guisubmenu>
 667             <guisubmenu>Variables</guisubmenu>
 668           </menuchoice> (see <xref linkend="fig.variables_view_open"/>)
 669         </para>
 670
 671
 672         <figure id="fig.variables_view_open_2">
 673           <title>Open the &expview; via the &varview; context menu</title>
 674           <mediaobject>
 675             <imageobject role="html">
 676               <imagedata align="center" fileref="img/en/xo-002/expressions_view_open_2.png" format="PNG"/>
 677             </imageobject>
 678             <imageobject role="fo">
 679               <imagedata align="center" fileref="img/en/xo-002/expressions_view_open_2.png" format="PNG" width="8cm"/>
 680             </imageobject>
 681           </mediaobject>
 682         </figure>
 683       </sect4>
 684
 685
 686       <sect4 id="sec.watch_expressions_open_3">
 687         <title>Open &expview; via context menu</title>
 688         <para>
 689            Unfortunately, yet this isn't implemented.
 690         </para>
 691       </sect4>
 692
 693       <sect4 id="sec.watch_expressions_remove">
 694         <title>Remove a watch expression</title>
 695         <para>
 696           An expression can be removed from the &expview; by activating the appropriate watch expression and typing <keycap>Del</keycap> or via the context menu <menuchoice><guimenuitem>Remove</guimenuitem></menuchoice>.
 697         </para>
 698       </sect4>
 699
 700
 701     </sect3>
 702   </sect2>
 703 </sect1>