← Back to branch summary

~ubuntu-branches/debian/lenny/fpc/lenny

« back to all changes in this revision

Viewing changes to fpcdocs/dbugintf.xml

  • Committer: Bazaar Package Importer
  • Author(s): Mazen Neifer, Torsten Werner, Mazen Neifer
  • Date: 2008-05-17 17:12:11 UTC
  • mfrom: (3.1.9 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080517171211-9qi33xhd9evfa0kg
Tags: 2.2.0-dfsg1-9
http://bugs.debian.org/477743
[ Torsten Werner ]
* Add Mazen Neifer to Uploaders field.

[ Mazen Neifer ]
* Moved FPC sources into a version dependent directory from /usr/share/fpcsrc
  to /usr/share/fpcsrc/${FPCVERSION}. This allow installing more than on FPC
  release.
* Fixed far call issue in compiler preventing building huge binearies.
  (closes: #477743)
* Updated building dependencies, recomennded and suggested packages.
* Moved fppkg to fp-utils as it is just a helper tool and is not required by
  compiler.

Show diffs side-by-side

added added

removed removed

Lines of Context:
fpcdocs/dbugintf.xml
 
1
<?xml version="1.0" encoding="ISO8859-1"?>
 
2
<fpdoc-descriptions>
 
3
<package name="fcl">
 
4
 
 
5
<!--
 
6
  ====================================================================
 
7
    dbugintf
 
8
  ====================================================================
 
9
-->
 
10
 
 
11
<module name="dbugintf">
 
12
<short>Unit to send commands to a debug server process</short>
 
13
<descr>
 
14
<p>
 
15
Use <file>dbugintf</file> to add debug messages to your application.
 
16
The messages are not sent to standard output, but are sent to a debug server
 
17
process which collects messages from various clients and displays them
 
18
somehow on screen. 
 
19
</p>
 
20
<p>
 
21
The unit is transparant in its use: it does not need initialization, it
 
22
will start the debug server by itself if it can find it: the program should
 
23
be called <file>debugserver</file> and should be in the <var>PATH</var>.
 
24
When the first debug message is sent, the unit will initialize itself.
 
25
</p>
 
26
<p>
 
27
The FCL contains a sample debug server (<file>dbugsvr</file>) which can be
 
28
started in advance, and which writes debug message to the console (both on
 
29
Windows and Linux). The Lazarus project contains a visual application which
 
30
displays the messages in a GUI.
 
31
</p>
 
32
<p>
 
33
The <file>dbugintf</file> unit relies on the <link id="SimpleIPC"/>
 
34
mechanism to communicate with the debug server, hence it works on all
 
35
platforms that have a functional version of that unit. It also uses
 
36
<var>TProcess</var> to start the debug server if needed, so the 
 
37
<link id="process"/> unit should also be functional.
 
38
</p>
 
39
</descr>
 
40
 
 
41
<topic name="debugservers">
 
42
<short>Writing a debug server</short>
 
43
<descr>
 
44
<p>
 
45
Writing a debug server is relatively easy. It should instantiate a
 
46
<var>TSimpleIPCServer</var> class from the <link id="SimpleIPC"/> unit, and
 
47
use the <var>DebugServerID</var> as <var>ServerID</var> identification. This
 
48
constant, as well as the record containing the message which is sent between 
 
49
client  and server is defined in the <file>msgintf</file> unit.
 
50
</p>
 
51
<p>
 
52
The <file>dbugintf</file> unit relies on the <link id="SimpleIPC"/>
 
53
mechanism to communicate with the debug server, hence it works on all
 
54
platforms that have a functional version of that unit. It also uses
 
55
<var>TProcess</var> to start the debug server if needed, so the 
 
56
<link id="process"/> unit should also be functional.
 
57
</p>
 
58
</descr>
 
59
</topic>
 
60
 
 
61
<!-- enumeration type Visibility: default -->
 
62
<element name="TDebugLevel">
 
63
<short>Level of the message.</short>
 
64
<descr>
 
65
<var>TDebugLevel</var> indicates the severity level of the debug 
 
66
message to be sent. By default, an informational message is sent. 
 
67
</descr>
 
68
<seealso>
 
69
<link id="SendDebugFmtEx"/>
 
70
<link id="SendDebugEx"/>
 
71
</seealso>
 
72
</element>
 
73
 
 
74
<!-- enumeration value Visibility: default -->
 
75
<element name="TDebugLevel.dlInformation">
 
76
<short>Informational message</short>
 
77
</element>
 
78
 
 
79
<!-- enumeration value Visibility: default -->
 
80
<element name="TDebugLevel.dlWarning">
 
81
<short>Warning message</short>
 
82
</element>
 
83
 
 
84
<!-- enumeration value Visibility: default -->
 
85
<element name="TDebugLevel.dlError">
 
86
<short>Error message</short>
 
87
</element>
 
88
 
 
89
<!-- procedure Visibility: default -->
 
90
<element name="SendBoolean">
 
91
<short>Send the value of a boolean variable</short>
 
92
<descr>
 
93
<var>SendBoolean</var> is a simple wrapper around <link id="SendDebug"/>
 
94
which sends the name and value of a boolean value as an informational
 
95
message.
 
96
</descr>
 
97
<errors>
 
98
None.
 
99
</errors>
 
100
<seealso>
 
101
<link id="SendDebug"/>
 
102
<link id="SendDateTime"/>
 
103
<link id="SendInteger"/>
 
104
<link id="SendPointer"/>
 
105
</seealso>
 
106
</element>
 
107
 
 
108
<!-- argument Visibility: default -->
 
109
<element name="SendBoolean.Identifier">
 
110
<short>Name of the boolean variable</short>
 
111
</element>
 
112
 
 
113
<!-- argument Visibility: default -->
 
114
<element name="SendBoolean.Value">
 
115
<short>Value of the boolean variable.</short>
 
116
</element>
 
117
 
 
118
<!-- procedure Visibility: default -->
 
119
<element name="SendDateTime">
 
120
<short>Send the value of a <var>TDateTime</var> variable.</short>
 
121
<descr>
 
122
<var>SendDateTime</var> is a simple wrapper around <link id="SendDebug"/>
 
123
which sends the name and value of an integer value as an informational
 
124
message. The value is converted to a string using the <link
 
125
id="#rtl.sysutils.DateTimeToStr">DateTimeToStr</link> call.
 
126
</descr>
 
127
<errors>
 
128
None.
 
129
</errors>
 
130
<seealso>
 
131
<link id="SendDebug"/>
 
132
<link id="SendBoolean"/>
 
133
<link id="SendInteger"/>
 
134
<link id="SendPointer"/>
 
135
</seealso>
 
136
</element>
 
137
 
 
138
<!-- argument Visibility: default -->
 
139
<element name="SendDateTime.Identifier">
 
140
<short>Name of the <var>TDateTime</var> variable</short>
 
141
</element>
 
142
 
 
143
<!-- argument Visibility: default -->
 
144
<element name="SendDateTime.Value">
 
145
<short>The actual date/time</short>
 
146
</element>
 
147
 
 
148
<element name="SendInteger">
 
149
<short>Send the value of an integer variable.</short>
 
150
<descr>
 
151
<var>SendInteger</var> is a simple wrapper around <link id="SendDebug"/>
 
152
which sends the name and value of an integer value as an informational
 
153
message. If <var>HexNotation</var> is <var>True</var>, then the value will be
 
154
displayed using hexadecimal notation.
 
155
</descr>
 
156
<errors>
 
157
None.
 
158
</errors>
 
159
<seealso>
 
160
<link id="SendDebug"/>
 
161
<link id="SendBoolean"/>
 
162
<link id="SendDateTime"/>
 
163
<link id="SendPointer"/>
 
164
</seealso>
 
165
</element>
 
166
 
 
167
<!-- argument Visibility: default -->
 
168
<element name="SendInteger.Identifier">
 
169
<short>Name of the integer variable</short>
 
170
</element>
 
171
 
 
172
<!-- argument Visibility: default -->
 
173
<element name="SendInteger.Value">
 
174
<short>The actual value</short>
 
175
</element>
 
176
 
 
177
<element name="SendInteger.HexNotation">
 
178
<short>Format integer using hexadecimal notation</short>
 
179
</element>
 
180
 
 
181
<element name="SendPointer">
 
182
<short>Send the value of a pointer variable.</short>
 
183
<descr>
 
184
<var>SendInteger</var> is a simple wrapper around <link id="SendDebug"/>
 
185
which sends the name and value of a pointer value as an informational
 
186
message. The pointer value is displayed using hexadecimal notation.
 
187
</descr>
 
188
<errors>
 
189
None.
 
190
</errors>
 
191
<seealso>
 
192
<link id="SendDebug"/>
 
193
<link id="SendBoolean"/>
 
194
<link id="SendDateTime"/>
 
195
<link id="SendInteger"/>
 
196
</seealso>
 
197
</element>
 
198
 
 
199
<!-- argument Visibility: default -->
 
200
<element name="SendPointer.Identifier">
 
201
<short>Name of the pointer variable</short>
 
202
</element>
 
203
 
 
204
<!-- argument Visibility: default -->
 
205
<element name="SendPointer.Value">
 
206
<short>The actual pointer value</short>
 
207
</element>
 
208
 
 
209
<!-- procedure Visibility: default -->
 
210
<element name="SendDebugEx">
 
211
<short>Send debug message other than informational messages</short>
 
212
<descr>
 
213
<p>
 
214
<var>SendDebugEx</var> allows to specify the debug level of the message
 
215
to be sent in <var>MType</var>. By default, <link id="SendDebug"/> uses 
 
216
informational messages.
 
217
</p>
 
218
<p>
 
219
Other than that the function of <var>SendDebugEx</var> is equal to that of
 
220
<var>SendDebug</var>
 
221
</p>
 
222
</descr>
 
223
<errors>
 
224
None.
 
225
</errors>
 
226
<seealso>
 
227
<link id="SendDebug"/>
 
228
<link id="SendDebugFmt"/>
 
229
<link id="SendDebugFmtEx"/>
 
230
</seealso>
 
231
</element>
 
232
 
 
233
<!-- argument Visibility: default -->
 
234
<element name="SendDebugEx.Msg">
 
235
<short>Message to be sent</short>
 
236
</element>
 
237
 
 
238
<!-- argument Visibility: default -->
 
239
<element name="SendDebugEx.MType">
 
240
<short>Debug level of the message to be sent</short>
 
241
</element>
 
242
 
 
243
<!-- procedure Visibility: default -->
 
244
<element name="SendDebug">
 
245
<short>Send a message to the debug server.</short>
 
246
<descr>
 
247
<p>
 
248
<var>SendDebug</var> sends the message <var>Msg</var> to the debug server as
 
249
an informational message (debug level <var>dlInformation</var>).
 
250
If no debug server is running, then an attempt will be made to start the 
 
251
server first.
 
252
</p>
 
253
<p>
 
254
The binary that is started is called <file>debugserver</file> and should be somewhere
 
255
on the <var>PATH</var>. A sample binary which writes received messages to
 
256
standard output is included in the FCL, it is called <file>dbugsrv</file>.
 
257
This binary can be renamed to <file>debugserver</file> or can be started
 
258
before the program is started.
 
259
</p>
 
260
</descr>
 
261
<errors>
 
262
Errors are silently ignored, any exception messages are stored in <link id="SendError"/>.
 
263
</errors>
 
264
<seealso>
 
265
<link id="SendDebugEx"/>
 
266
<link id="SendDebugFmt"/>
 
267
<link id="SendDebugFmtEx"/>
 
268
</seealso>
 
269
</element>
 
270
 
 
271
<!-- argument Visibility: default -->
 
272
<element name="SendDebug.Msg">
 
273
<short>The message to be sent to the server.</short>
 
274
</element>
 
275
 
 
276
<!-- procedure Visibility: default -->
 
277
<element name="SendMethodEnter">
 
278
<short>Send method enter message</short>
 
279
<descr>
 
280
<p>
 
281
<var>SendMethodEnter</var> sends a "Entering <var>MethodName</var>" message 
 
282
to the debug server. After that it increases the message indentation 
 
283
(currently 2 characters). By sending a corresponding <link id="SendMethodExit"/>, 
 
284
the indentation of messages can be decreased again.
 
285
</p>
 
286
<p>
 
287
By using the <var>SendMethodEnter</var> and <var>SendMethodExit</var>
 
288
methods at the beginning and end of a procedure/method, 
 
289
it is possible to visually trace program execution.
 
290
</p>
 
291
</descr>
 
292
<errors>
 
293
None.
 
294
</errors>
 
295
<seealso>
 
296
<link id="SendDebug"/>
 
297
<link id="SendMethodExit"/>
 
298
<link id="SendSeparator"/>
 
299
</seealso>
 
300
</element>
 
301
 
 
302
<!-- argument Visibility: default -->
 
303
<element name="SendMethodEnter.MethodName">
 
304
<short>Name of the entered method</short>
 
305
</element>
 
306
 
 
307
<!-- procedure Visibility: default -->
 
308
<element name="SendMethodExit">
 
309
<short>Send method exit message </short>
 
310
<descr>
 
311
<p>
 
312
<var>SendMethodExit</var> sends a "Exiting <var>MethodName</var>" message 
 
313
to the debug server. After that it decreases the message indentation 
 
314
(currently 2 characters). By sending a corresponding <link
 
315
id="SendMethodEnter"/>, the indentation of messages can be increased again.
 
316
</p>
 
317
<p>
 
318
By using the <var>SendMethodEnter</var> and <var>SendMethodExit</var>
 
319
methods at the beginning and end of a procedure/method, 
 
320
it is possible to visually trace program execution.
 
321
</p>
 
322
<p>
 
323
Note that the indentation level will not be made negative.
 
324
</p>
 
325
</descr>
 
326
<errors>
 
327
None.
 
328
</errors>
 
329
<seealso>
 
330
<link id="SendDebug"/>
 
331
<link id="SendMethodEnter"/>
 
332
<link id="SendSeparator"/>
 
333
</seealso>
 
334
</element>
 
335
 
 
336
<!-- argument Visibility: default -->
 
337
<element name="SendMethodExit.MethodName">
 
338
<short>Name of the method that is entered</short>
 
339
</element>
 
340
 
 
341
<!-- procedure Visibility: default -->
 
342
<element name="SendSeparator">
 
343
<short>Send a separator message</short>
 
344
<descr>
 
345
<var>SendSeparator</var> is a simple wrapper around <link id="SendDebug"/>
 
346
which sends a short horizontal line to the debug server. It can be used to 
 
347
visually separate execution of blocks of code or blocks of values.
 
348
</descr>
 
349
<errors>
 
350
None.
 
351
</errors>
 
352
<seealso>
 
353
<link id="SendDebug"/>
 
354
<link id="SendMethodEnter"/>
 
355
<link id="SendMethodExit"/>
 
356
</seealso>
 
357
</element>
 
358
 
 
359
<!-- procedure Visibility: default -->
 
360
<element name="SendDebugFmt">
 
361
<short>Format and send a debug message</short>
 
362
<descr>
 
363
<var>SendDebugFmt</var> is a utility routine which formats a message by
 
364
passing <var>Msg</var> and <var>Args</var> to <link
 
365
id="#rtl.sysutils.format">Format</link> and sends the result to the debug server
 
366
using <link id="SendDebug"/>. It exists mainly to avoid the
 
367
<var>Format</var> call in calling code.
 
368
</descr>
 
369
<errors>
 
370
None.
 
371
</errors>
 
372
<seealso>
 
373
<link id="SendDebug"/>
 
374
<link id="SendDebugEx"/>
 
375
<link id="SendDebugFmtEx"/>
 
376
<link id="#rtl.sysutils.format"/>
 
377
</seealso>
 
378
</element>
 
379
 
 
380
<!-- argument Visibility: default -->
 
381
<element name="SendDebugFmt.Msg">
 
382
<short>Template for message</short>
 
383
</element>
 
384
 
 
385
<!-- argument Visibility: default -->
 
386
<element name="SendDebugFmt.Args">
 
387
<short>Arguments to be inserted in template</short>
 
388
</element>
 
389
 
 
390
<!-- procedure Visibility: default -->
 
391
<element name="SendDebugFmtEx">
 
392
<short>Format and send message with alternate type</short>
 
393
<descr>
 
394
<var>SendDebugFmtEx</var> is a utility routine which formats a message by
 
395
passing <var>Msg</var> and <var>Args</var> to <link
 
396
id="#rtl.sysutils.format">Format</link> and sends the result to the debug server
 
397
using <link id="SendDebugEx"/> with Debug level <var>MType</var>. It exists mainly to avoid the
 
398
<var>Format</var> call in calling code.
 
399
</descr>
 
400
<errors>
 
401
None.
 
402
</errors>
 
403
<seealso>
 
404
<link id="SendDebug"/>
 
405
<link id="SendDebugEx"/>
 
406
<link id="SendDebugFmt"/>
 
407
<link id="#rtl.sysutils.format"/>
 
408
</seealso>
 
409
</element>
 
410
 
 
411
<!-- argument Visibility: default -->
 
412
<element name="SendDebugFmtEx.Msg">
 
413
<short>Message template</short>
 
414
</element>
 
415
 
 
416
<!-- argument Visibility: default -->
 
417
<element name="SendDebugFmtEx.Args">
 
418
<short>Arguments to insert in template</short>
 
419
</element>
 
420
 
 
421
<!-- argument Visibility: default -->
 
422
<element name="SendDebugFmtEx.MType">
 
423
<short>Debug level of message</short>
 
424
</element>
 
425
 
 
426
<!-- function Visibility: default -->
 
427
<element name="StartDebugServer">
 
428
<short>Start the debug server</short>
 
429
<descr>
 
430
<p>
 
431
<var>StartDebugServer</var> attempts to start the debug server. The process
 
432
started is called <file>debugserver</file> and should be located in the
 
433
<var>PATH</var>.
 
434
</p>
 
435
<p>
 
436
Normally this function should not be called. The <link id="SendDebug"/> call
 
437
will attempt to start the server by itself if it is not yet running.
 
438
</p>
 
439
</descr>
 
440
<errors>
 
441
On error, <var>False</var> is returned.
 
442
</errors>
 
443
<seealso>
 
444
<link id="SendDebug"/>
 
445
<link id="InitDebugClient"/>
 
446
</seealso>
 
447
</element>
 
448
 
 
449
<!-- function result Visibility: default -->
 
450
<element name="StartDebugServer.Result">
 
451
<short>True if started succesfully, false otherwise</short>
 
452
</element>
 
453
 
 
454
<!-- procedure Visibility: default -->
 
455
<element name="InitDebugClient">
 
456
<short>Initialize the debug client.</short>
 
457
<descr>
 
458
<p>
 
459
<var>InitDebugClient</var> starts the debug server and then performs all
 
460
necessary initialization of the debug IPC communication channel.
 
461
</p>
 
462
<p>
 
463
Normally this function should not be called. The <link id="SendDebug"/> call
 
464
will initialize the debug client when it is first called.
 
465
</p>
 
466
</descr>
 
467
<errors>
 
468
None.
 
469
</errors>
 
470
<seealso>
 
471
<link id="SendDebug"/>
 
472
<link id="StartDebugServer"/>
 
473
</seealso>
 
474
</element>
 
475
 
 
476
<!-- constant Visibility: default -->
 
477
<element name="SendError">
 
478
<short>Last error in the debug system.</short>
 
479
<descr>
 
480
Whenever a call encounteres an exception, the exception message is stored in
 
481
this variable.
 
482
</descr>
 
483
</element>
 
484
 
 
485
<!-- resource string Visibility: default -->
 
486
<element name="SProcessID">
 
487
<short>String used when sending identification message to the server.</short>
 
488
</element>
 
489
 
 
490
<!-- resource string Visibility: default -->
 
491
<element name="SEntering">
 
492
<short>String used when sending method enter message.</short>
 
493
</element>
 
494
 
 
495
<!-- resource string Visibility: default -->
 
496
<element name="SExiting">
 
497
<short>String used when sending method exit message.</short>
 
498
</element>
 
499
 
 
500
<!-- resource string Visibility: default -->
 
501
<element name="SSeparator">
 
502
<short>String used when sending a separator line.</short>
 
503
</element>
 
504
 
 
505
</module> <!-- dbugintf -->
 
506
</package>
 
507
</fpdoc-descriptions>