xcos_debug_gui function added for a simple use of the Debug block
[scilab.git] / scilab / modules / xcos / help / en_US / xcos_debug_gui.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Serge Steer
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13
14 <refentry xml:id="xcos_debug_gui" xml:lang="en"
15           xmlns="http://docbook.org/ns/docbook"
16           xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg"
18           xmlns:scilab="http://www.scilab.org"
19           xmlns:ns4="http://www.w3.org/1999/xhtml"
20           xmlns:mml="http://www.w3.org/1998/Math/MathML"
21           xmlns:db="http://docbook.org/ns/docbook">
22   <refnamediv>
23     <refname>xcos_debug_gui</refname>
24
25     <refpurpose>Interactive debugging function to be used in the Debug Xcos
26     block</refpurpose>
27   </refnamediv>
28
29   <refsection>
30     <title>Description</title>
31
32     <para>The Xcos Debug block allows to set a Scilab instruction that is
33     executed before and after the execution of each blocks during the
34     simulation. Setting the instruction xcos_debug_gui() for the Debug block
35     instruction makes a graphical user interface to be opened at the beginning
36     of the simulation. This GUI allows to interactive debug. In particular it
37     is possible to dynamically specify conditions for which the simulation
38     will be suspended (break points). When halted on a break point user can
39     examine the current values, state, input,... of the block.</para>
40
41     <para>At any time the user can specify break points by a set of cumulative
42     conditions:</para>
43
44     <itemizedlist>
45       <listitem>
46         <para>The flag value for which the current block is called</para>
47       </listitem>
48
49       <listitem>
50         <para>The current date value</para>
51       </listitem>
52
53       <listitem>
54         <para>If the break takes place before and/or the block call</para>
55       </listitem>
56
57       <listitem>
58         <para>The value of a Scilab boolean expression, the break is
59         active if the condition evaluates to true. This expression may
60         use the block variable <link
61         linkend="C_struct">C_struct</link> that contains the current
62         block elements and Scilab functions <link
63         linkend="curblock">curblock</link> and <link
64         linkend="scicos_time">scicos_time</link>. </para>
65       </listitem>
66     </itemizedlist>
67
68     <mediaobject>
69       <imageobject>
70         <imagedata fileref="../images/Xcos_Debug.png" format="PNG"/>
71       </imageobject>
72     </mediaobject>
73
74     <para>When the simulation is suspended, the graphical user interface shows
75     the current time and current flag values, the block number and the path of
76     the block in the super blocks hierarchy. </para>
77
78     <para>The "Next" button restart the simulation till the next suspending
79     condition</para>
80
81     <para>The "End debug" button disable all conditions letting the simulation
82     going on freely up to the end</para>
83
84     <para>The "Pause" button allows to interactively observe the block data
85     structure associated to the current block executing Scilab instructions in
86     the Scilab console. User must enter the "return" instruction to go
87     back.</para>
88   </refsection>
89
90  
91   <refsection>
92     <title>Authors</title>
93
94     <simplelist type="vert">
95       <member>Serge Steer, INRIA</member>
96     </simplelist>
97   </refsection>
98
99   <refsection>
100     <title>History</title>
101
102     <revhistory>
103       <revision>
104         <revnumber>0.0</revnumber>
105
106         <revdescription>Function xcos_debug_gui added</revdescription>
107       </revision>
108     </revhistory>
109   </refsection>
110 </refentry>