docs/en/target/debug.txt

   1 .. index::
   2         single: The Trace Library and the Interactive Debugger; Introduction
   3
   4 ==============================================
   5 The Trace Library and the Interactive Debugger
   6 ==============================================
   7
   8 In this chapter we will learn about the Trace Library and the Interactive Debugger
   9
  10 .. index::
  11         pair: The Trace Library and the Interactive Debugger; Loading the Trace library
  12
  13 Loading the Trace library
  14 =========================
  15
  16 To start using the Trace library, We must load it first!
  17
  18 .. code-block:: ring
  19
  20         load "tracelib.ring"
  21
  22 .. index::
  23         pair: The Trace Library and the Interactive Debugger; Trace All Events
  24
  25 Trace All Events
  26 ================
  27
  28 The next example demonstrates the Trace library usage to trace all events.
  29
  30 .. code-block:: ring
  31
  32         # Trace All Events
  33         trace(:AllEvents)
  34
  35         see "Hello, world!" + nl
  36         see "Welcome" + nl
  37         see "How are you?" +nl
  38
  39         mytest()
  40
  41         new myclass { mymethod() }
  42
  43         func mytest
  44                 see "Message from mytest" + nl
  45
  46         class myclass
  47                 func mymethod
  48                         see "Message from mymethod" + nl
  49
  50
  51 .. index::
  52         pair: The Trace Library and the Interactive Debugger; Trace control flow between functions
  53
  54 Trace control flow between functions
  55 ====================================
  56
  57 The next example demonstrates the Trace library usage
  58 to trace the control flow between functions.
  59
  60 .. code-block:: ring
  61
  62         Trace(:Functions)
  63
  64         test1()
  65
  66         func test1
  67                 see :test1 + nl
  68                 test2()
  69
  70         func test2
  71                 see :test2 + nl
  72                 see test3() + nl
  73
  74         func test3
  75                 see :test3 + nl
  76                 return "test 3 output"
  77
  78 .. index::
  79         pair: The Trace Library and the Interactive Debugger; Pass Error
  80
  81 Pass Error
  82 ==========
  83
  84 The next example demonstrates the Trace library usage
  85 to pass an error!
  86
  87 .. code-block:: ring
  88
  89         Trace(:PassError)
  90
  91         test1()
  92
  93         func test1
  94                 x = 10
  95                 see :test1 + nl
  96                 test2() # Runtime Error!
  97                 see "We can continue!"
  98
  99 .. index::
 100         pair: The Trace Library and the Interactive Debugger; Interactive Debugger
 101
 102 Interactive Debugger
 103 ====================
 104
 105 The next example demonstrates the Trace library usage
 106 to use the Interactive Debugger
 107
 108 .. code-block:: ring
 109
 110         Trace(:Debugger)
 111
 112         test1()
 113         see "good bye!" + nl
 114
 115         func test1
 116                 x = 10
 117                 see :test1 + nl
 118                 t = 12
 119                 test2() # Runtime Error!
 120                 see "After Error!" +nl
 121                 see "t = " see t see nl
 122                 see "x = " see x see nl
 123
 124 .. index::
 125         pair: The Trace Library and the Interactive Debugger; Execute Program Line by Line
 126
 127 Execute Program Line by Line
 128 ============================
 129
 130 The next example demonstrates the Trace library usage
 131 to execute the program line by line!
 132
 133 .. code-block:: ring
 134
 135         Trace(:LineByLine)
 136
 137         test1()
 138
 139         func test1
 140                 x = 10
 141                 see :test1 + nl
 142                 t = 12
 143                 test2()
 144                 see "After Error!" +nl
 145                 see "t = " + t + nl
 146
 147 .. index::
 148         pair: The Trace Library and the Interactive Debugger; BreakPoint
 149
 150 BreakPoint
 151 ==========
 152
 153 The next example demonstrates the Trace library usage
 154 to stop at a breakpoint!
 155
 156 .. code-block:: ring
 157
 158         test1()
 159
 160         func test1
 161                 x = 10
 162                 see :test1 + nl
 163                 t = 12
 164                 BreakPoint()
 165                 see "After breakpoint!" +nl
 166                 see "t = " + t + nl
 167                 see "End of program!" + nl
 168
 169 .. index::
 170         pair: The Trace Library and the Interactive Debugger; Disable BreakPoints
 171
 172 Disable BreakPoints
 173 ===================
 174
 175 The next example demonstrates the Trace library usage
 176 and how to disable the Breakpoints!
 177
 178 .. code-block:: ring
 179
 180         NoBreakPoints()
 181
 182         test1()
 183
 184         func test1
 185                 x = 10
 186                 see :test1 + nl
 187                 t = 12
 188                 BreakPoint()
 189                 see "After breakpoint!" +nl
 190                 see "t = " + t + nl
 191                 see "End of program!" + nl
 192
 193 .. index::
 194         pair: The Trace Library and the Interactive Debugger; Using the Interactive Debugger
 195
 196 Using the Interactive Debugger
 197 ==============================
 198
 199 The next example uses a Breakpoint to open the Interactive Debugger!
 200
 201 .. code-block:: ring
 202
 203         load "tracelib.ring"
 204
 205         test1()
 206
 207         func test1
 208                 x = 10
 209                 see :test1 + nl
 210                 t = 12
 211                 BreakPoint()
 212                 see "After breakpoint!" +nl
 213                 see "t = " + t + nl
 214                 see "End of program!" + nl
 215
 216
 217 Screen Shots:
 218
 219 We have the Interactive Debugger at the Breakpoint!
 220
 221 .. image:: debugshot1.png
 222         :alt: Interactive Debugger
 223
 224 We can print the variables values
 225
 226 .. image:: debugshot2.png
 227         :alt: Interactive Debugger
 228
 229 We can change the variables values then continue execution
 230
 231 .. image:: debugshot3.png
 232         :alt: Interactive Debugger
 233
 234 We can run the Interactive Debugger in the Output Window
 235
 236 .. image:: debugshot4.png
 237         :alt: Interactive Debugger
 238