Debian Codegraph @

ipl/packs/itweak/itweak.htm

raw
1 <HTML>
2 <HEAD>
3 <TITLE>Itweak: Interactive Icon Debugging</TITLE>
4 </HEAD>
5 <BODY BGCOLOR=#FFFFDF>
6
7 <CENTER>
8 <H1><EM>itweak</EM><BR>An Interactive Debugging Utility for the<BR>Icon Programming Language</H1>
9 <P>Release 2.21
10 <P>H&aring;kan S&ouml;derstr&ouml;m (<tt>[email protected]</tt>)
11 <P>S&ouml;derstr&ouml;m Programvaruverkstad AB<BR>Bandhagsv&auml;gen 51<BR>S-122 42 Enskede, Sweden
12 </CENTER>
13
14 <H2>Contents</H2>
15
16 <OL>
17 <LI><A HREF="#intro">Introduction, Acknowledgements and Non-Warranty</A>
18 <LI><A HREF="#prereq">Prerequisites</A>
19 <LI><A HREF="#install">Installing <EM>itweak</EM></A>
20 <UL>
21 <LI><A HREF="#unix">Unix</A>
22 <LI><A HREF="#other-platforms">Other Platforms, or Platforms Without Make</A>
23 </UL>
24 <LI><A HREF="#samples">Debugging Samples</A>
25 <UL>
26 <LI><A HREF="#canned-session">Canned Debugging Session</A>
27 <LI><A HREF="#sample-commands">Sample Debugging Commands</A>
28 </UL>
29 <LI><A HREF="#preparing-debug">Preparing for a Debugging Session</A>
30 <UL>
31 <LI><A HREF="#tweak-link">Tweaking and Linking an Icon Program</A>
32 <LI><A HREF="#re-tweaking">Note on Re-Tweaking Files</A>
33 <LI><A HREF="#quirks-limit"><EM>itweak</EM> Quirks and Limitations</A>
34 </UL>
35 <LI><A HREF="#debug-session">The Debugging Session</A>
36 <UL>
37 <LI><A HREF="#start-session">Starting a Debugging Session</A>
38 <LI><A HREF="#env-variables">Run-Time Environment Variables</A>
39 <LI><A HREF="#debug-commands">Debugging Commands: Overview</A>
40 <UL>
41 <LI><A HREF="#keyw-abbrev">Keyword Abbreviations</A>
42 <LI><A HREF="#breakpoints">
43 <LI><A HREF="#expressions">Expressions</A>
44 <LI><A HREF="#printing-cmd">Commands for Printing</A>
45 </UL>
46 <LI><A HREF="#run-quirks-limit">Run-Time Quirks, Limitations</A>
47 </UL>
48 <LI><A HREF="#performance">Performance Considerations</A>
49 <LI><A HREF="#impl-notes">Implementation Notes (The Hidden Art of Tweaking)</A>
50 </OL>
51
52 <BLOCKQUOTE>Copyright &copy; 1994-1996 Hakan Soderstrom and Soderstrom Programvaruverkstad AB, Sweden. Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice and this permission notice appear in all copies of the software and related documentation.
53 </BLOCKQUOTE>
54
55 <H2><A NAME="intro">1. Introduction, Acknowledgements and Non-Warranty</A></H2>
56
57 <P><EM>itweak</EM> is an Icon interactive debugging utility. The idea is that
58 you compile your Icon program to ucode files (<tt>.u1</tt>, <tt>.u2</tt>).
59 <EM>itweak</EM> then tweaks the ucode, inserting potential breakpoints.
60 The resulting ucode files are linked with a debugging run-time and off
61 you go.
62
63 <P>The <EM>itweak</EM> system provides you with many of the facilities
64 you would
65 expect from an interactive debugger, including the ability to evaluate
66 a wide range of Icon expressions.
67 Personally I wouldn't like to be without this tool, but I may be biased.
68 It can be used both for finding bugs and to convince oneself that an
69 Icon program indeed works the intended way.
70
71 <P><EM>itweak</EM> owes a lot to the pioneering <em>debugify</em> system
72 by Charles A. Shartsis.
73 This heritage is gratefully acknowledged. What <EM>itweak</EM>
74 offers over <em>debugify</em> is radically improved performance (in time as
75 well as space) and a more fully-fledged run-time system.
76
77 <P>The author believes the software is useful but wouldn't imagine it is
78 free from bugs.
79 The software is provided "as-is" and without warranty of any kind.
80 Please send bug reports, change requests, and other comments to the
81 address above.
82
83 <H2><A NAME="prereq">2. Prerequisites</A></H2>
84
85 <P><EM>itweak</EM> has been tested with Icon 8.10 and 9.0 under Unix
86 (SunOS 4.1.4) and DOS.
87 The software is completely written in Icon, and should be as portable
88 as Icon itself.
89
90 <H2><A NAME="install">3. Installing <EM>itweak</EM></A></H2>
91
92 <P>Installation is straightforward.
93 For Unix there is a makefile that does most of the job.
94
95 <H3><A NAME="unix">Unix</A></H3>
96
97 <P>Under Unix, type <tt>make</tt> in the installation directory.
98 The following files are generated.
99 <DL>
100 <DT>itweak<DD>an Icon 'executable'.
101 Copy it to a commonly accessible directory and include it in your
102 PATH.
103 <DT>dbg_run.u1, dbg_run.u2
104 <DD>These files constitute the <em>debugging run-time</em> system which will
105 be linked with your tweaked programs.
106 Make the debugging run-time available to the Icon linker by including
107 its directory in the IPATH environment variable.
108 Or, alternatively, make sure that the <tt>dbg_run.u</tt> files are
109 present in the same directory as the program you are going to debug.
110 </DL>
111
112 <H3><A NAME="other-platforms">Other Platforms, or Platforms Without Make</A></H3>
113
114 <P><EM>itweak</EM> comes with two Icon source files, <tt>itweak.icn</tt> and <tt>dbg_run.icn</tt>.
115 Run the following command to produce the <EM>itweak</EM> program,
116 <P><CODE>
117 icont itweak.icn
118 </CODE>
119 <P>Put <EM>itweak</EM> (the resulting file) in a commonly accessible directory and
120 include it in your PATH.
121 (If you can, you should of course use the Icon compiler to produce <EM>itweak</EM>.)
122 Now run the following command,
123 <P><CODE>
124 icont -c dbg_run.icn
125 </CODE>
126 <P>The resulting files (<tt>dbg_run.u1, dbg_run.u2</tt>) constitute the
127 <em>debugging run-time</em> system which will be linked with your
128 tweaked programs.
129
130 <P>Make the debugging run-time available to the Icon linker by including
131 its directory in the IPATH environment variable.
132 Or, alternatively, make sure that the <tt>dbg_run.u</tt> files are
133 present in the same directory as the program you are going to debug.
134
135 <H2><A NAME="samples">4. Debugging Samples</A></H2>
136
137 <P>There are at least two ways you may examine <EM>itweak</EM> without
138 committing yourself too heavily to it.
139
140 <H3><A NAME="canned-session">Canned Debugging Session</A></H3>
141
142 <P>The <EM>itweak</EM> distribution comes with a demo.
143 Under Unix, type <tt>make demo</tt> to make it happen.
144
145 <P>On other platforms, or on platforms without <EM>make:</EM> do the following commands.
146 <P><CODE>
147 icont -c ipxref.icn<BR>
148 icont -c options.icn<BR>
149 itweak -o samp_ini.icn ipxref options<BR>
150 icont -c samp_ini.icn<BR>
151 icont -o sample ipxref.u1 options.u1<BR>
152 setenv DBG_INPUT demo.cmd<BR>
153 sample ipxref.icn<BR>
154 </CODE>
155 <P>The commands compile and tweak a sample program.
156 The source files are <tt>ipxref.icn</tt> and <tt>options.icn</tt>.
157 The resulting 'executable' is called <tt>sample</tt>.
158 The last command runs a canned debugging session.
159
160 <P>Debugging commands for the demo are taken from the file <tt>demo.cmd</tt>.
161 To make the demo more meaningful you should open an editor on
162 <tt>demo.cmd</tt> and compare it to the output of the debugging session.
163 The commands are annotated.
164
165 <H3><A NAME="sample-commands">Sample Debugging Commands</A></H3>
166
167 <P>Read this to get a first impression of what kinds of debugging commands
168 <EM>itweak</EM> offer.
169 For reading convenience all commands are spelled out fully.
170 (Commands may be abbreviated as long as the abbreviation is unambiguous.)
171
172 <P>Set a breakpoint on a source code line and then let the program run to
173 its first break.
174 <P><CODE>
175 break 88
176 goon
177 </CODE>
178 <P>In the following examples we omit the <tt>goon</tt> command which makes
179 the program continue until the next break (or until it exits).
180
181 <P>Print the current value of a simple variable (<tt>word</tt>).
182 <P><CODE>
183 print word
184 </CODE>
185 <P>Attach a macro which automatically prints <tt>word</tt> every time we hit
186 this breakpoint.
187 <P><CODE>
188 do .<BR>
189 print word<BR>
190 end<BR>
191 </CODE>
192 <P>Attach a condition to the breakpoint which causes a break only if
193 <tt>word</tt> contains the string <tt>buffer</tt>.
194 <P><CODE>
195 cond . word == "buffer"
196 </CODE>
197 <P>The dot means <em>the current breakpoint</tt>.
198
199 <P>Now some more advanced printing:
200 Print every value generated by an expression.
201 This is useful if the variable contains a list, for example.
202 <P><CODE>
203 eprint !resword
204 </CODE>
205 <P>You may use subscripting and record field references when printing an
206 expression:
207 <P><CODE>
208 print prec[1].pname
209 </CODE>
210 <P>The printing commands actually accept almost all Icon expressions.
211 You may invoke procedures or Icon functions, for instance.
212
213 <P>You may use the <tt>info</tt> command to get information about a
214 breakpoint, source files, local or global variables, among other things:
215 <P><CODE>
216 info break .<BR>
217 info files<BR>
218 info local<BR>
219 info global<BR>
220 </CODE>
221 <P>These are not all commands.
222 Please refer to the special section on
223 <A HREF="#debug-commands">debugging commands</A>.
224 The <EM>itweak</EM> on-line help contains details about all available commands.
225
226 <H2><A NAME="preparing-debug">5. Preparing for a Debugging Session</A></H2>
227
228 <P>In order to debug an Icon program you will need to go through
229 the following major steps.
230 These steps assume you have installed <EM>itweak</EM> as described above.
231 <OL>
232 <LI>Compile the Icon source files (usually <tt>icont -c</tt>).
233 <LI>Tweak some or all of the program's ucode files.
234 <LI>Compile the Icon source file generated by <EM>itweak</EM>.
235 <LI>Link the tweaked files.
236 <LI>Run an interactive debugging session.
237 </OL>
238
239 <P>The demo described in the previous section provides an example.
240 The next few sections go more into detail.
241
242 <H3><A NAME="tweak-link">Tweaking and Linking an Icon Program</A></H3>
243
244 <P>Let us assume you have a program built from source files named
245 <tt>alpha.icn</tt>, <tt>beta.icn</tt>, and <tt>gamma.icn</tt>.
246 Compile all source files, but do not link them yet.
247 A suitable command is
248 <P><CODE>
249 icont -c alpha.icn beta.icn gamma.icn
250 </CODE>
251 <P>This will produce <tt>.u1</tt> and <tt>.u2</tt> (i.e. ucode) files for
252 each of the source files.
253
254 <P>It is not necessary to tweak all files. However, you will be able to set
255 breakpoints only in tweaked files. In order to illuminate this point, let
256 us assume you decide to tweak only files <tt>alpha</tt> and <tt>gamma</tt>.
257 Do this the following way.
258 Note that the <EM>itweak</EM> command takes base file names, omitting the file
259 name extension (<tt>.u1</tt>, for example).
260 <P><CODE>
261 itweak alpha gamma
262 </CODE>
263 <P>The above command will tweak <tt>alpha.u1</tt> and <tt>gamma.u1</tt> and one of
264 the <tt>.u2</tt> files.
265 It is important to tweak the files in a single <EM>itweak</EM> command.
266 For reasons described in the <A HREF="#quirks-limit">quirks</A> section
267 the general recommendation is that you include the file containing the
268 <B>main</B> procedure in the set of tweaked files.
269
270 <P>Whenever a ucode file is tweaked the original file is saved under a
271 different name.
272 A <tt>.u1</tt> file will have its extension changed to <tt>.u1~</tt>.
273 A tweaked <tt>.u2</tt> file will have its extension changed to <tt>.u2~</tt>.
274
275 <P>Later, when running the program, reference will only be made to source
276 files, not to ucode files.
277
278 <P>The <EM>itweak</EM> command produces an additional Icon file.
279 Its default name is <tt>dbg_init.icn</tt>.
280 You may change the name of this file by using the <tt>-o</tt> command line option.
281 For instance, the following is a possible command,
282 <P><CODE>
283 itweak -o proginit.icn alpha gamma
284 </CODE>
285 <P>This command will generate a file named <tt>proginit.icn</tt>, but
286 otherwise perform the same function as the <EM>itweak</EM> command above.
287 You must compile the generated Icon file.
288 The following command does this (now assuming the default name has been used).
289 <P><CODE>
290 icont -c dbg_init.icn
291 </CODE>
292 <P>Finally link the program as you would normally do it.
293 Like this, for instance,
294 <P><CODE>
295 icont alpha.u beta.u gamma.u
296 </CODE>
297 <P>The <EM>itweak</EM> command tweaks one of the <tt>.u2</tt> files involved.
298 It inserts the equivalent of <B>link</B> statements.
299 This will, in effect, add <tt>dbg_init.icn</tt> and <tt>dbg_run.u</tt> to
300 the link list.
301 The <tt>dbg_init.u</tt> files will usually be present in the current
302 directory.
303 Of course the <tt>dbg_run.u</tt> files may also reside in the current
304 directory.
305 However, it is often more useful to have the run-time files in a
306 separate directory which is included in the IPATH environment
307 variable.
308
309 If the linkage is successful, the result is an executable program
310 <tt>alpha</tt> (under Unix).
311
312 <H3><A NAME="re-tweaking">Note on Re-Tweaking Files</A></H3>
313
314 <P>Usually you would develop a program in an edit-compile-debug cycle.
315 <EM>itweak</EM> notices if a file is already tweaked and does not tweak it a
316 second time. Thus you may run the same <EM>itweak</EM> command after you have
317 modified and compiled just one of the source files. This means the
318 <EM>itweak</EM> command is suited for inclusion in a Makefile.
319
320 <H3><A NAME="quirks-limit"><EM>itweak</EM> Quirks and Limitations</A></H3>
321
322 <P><EM>itweak</EM> and the debugging run-time introduce numerous
323 global names for its own use.
324 A common prefix is used on all such names to minimize the risk of name
325 clashes with your program.
326 The prefix is '<tt>__dbg_</tt>' (beginning with a double underscore).
327 It is, of course, possible for the target program to interfere with
328 the debugging run-time, possibly causing it to crash.
329
330 <P><EM>itweak</EM> detects the <B>main</B> Icon procedure of your program.
331 It inserts code for executing a parameterless procedure named
332 <tt>__dbg_init</tt> before anything else.
333 This procedure initializes the run-time environment.
334 (The procedure is generated by <EM>itweak</EM> as part of the <tt>dbg_init.icn</tt> file.)
335
336 <P>If you omit the file containing <B>main</B> from the set of tweaked
337 files you must modify your program to invoke <tt>__dbg_init</tt> before
338 execution reaches a tweaked file.
339 Otherwise the program will terminate with a run-time error.
340
341 <P>This is one reason why tweaked ucode files are not suited for shared
342 libraries.
343 Tweaking a file in a way marks it for a particular program.
344 You (or somebody else) may attempt to tweak the same file in order to
345 use it in a different program, but <EM>itweak</EM> will not touch it,
346 because it has been tweaked already.
347 There will probably be a conflict at linkage time, however: <em>__dbg_init:
348 inconsistent redeclaration</em>.
349 What you have to do in this case is erase the ucode files and
350 recompile and tweak from scratch.
351
352 <P>For each tweaked file <EM>itweak</EM> creates a global variable
353 holding a set of active breakpoints.
354 The name of this variable contains the base name of the file.
355 This limits file names to the syntax accepted as Icon identifiers.
356
357 <H2><A NAME="debug-session">6. The Debugging Session</A></H2>
358
359 <P>This section describes what a debugging session looks like.
360
361 <H3><A NAME="start-session">Starting a Debugging Session</A></H3>
362
363 <P>After having tweaked and linked your program according to the
364 description above you should be able to start it as usual.
365 It will behave slightly different, however.
366 After starting up a '<tt>$</tt>' prompt will appear (on standard error).
367 The prompt means you are expected to enter a debugging command (on
368 standard input).
369
370 <P>Detailed command descriptions are available on-line through the
371 <tt>help</tt> command.
372 Type <tt>help</tt> to see a list of available commands.
373 Type <tt>help <i>command</i></tt> to get a description of a particular
374 command.
375
376 <H3><A NAME="env-variables">Run-Time Environment Variables</A></H3>
377
378 <P>Environment variables may be used to re-direct debugging
379 input and output.
380
381 <DL>
382 <DT>DBG_INPUT<DD>if set to a file name will cause debugging commands
383 to be read from the file.
384 If end-of-file is encountered remaining commands will be taken from
385 standard input.
386
387 <DT>DBG_OUTPUT<DD>if set to a file name will cause debugging output to
388 be written to the file.
389 </DL>
390
391 <H3><A NAME="debug-commands">Debugging Commands: Overview</A></H3>
392
393 <P>The debugging commands will enable you to control and monitor the
394 execution of your program.
395 This section contains general information and some examples.
396 Detailed descriptions are available on-line through the <tt>help</tt> command.
397
398 <H4><A NAME="keyw-abbrev">Keyword Abbreviations</A></H4>
399
400 <P>All debugging command keywords may be abbreviated as long as the
401 abbreviation is unambiguous.
402 For instance, <tt>goon nobreak</tt> may usually be written <tt>g no</tt>.
403
404 <P>The reason we say <em>usually</em> is that you may define new commands
405 by means of the <tt>macro</tt> command.
406 Macro names are subject to the same abbreviation rules as built-in
407 commands.
408
409 <H4><A NAME="breakpoints">Breakpoints</A></H4>
410
411 <H5><A NAME="setting-clearing-brk">Setting and Clearing a Breakpoint</A></H5>
412
413 <P>The <tt>break</tt> command defines a breakpoint on a source line or on a
414 number of consecutive source lines.
415 The break will take effect <B>after</B> the expression on the source
416 line has been evaluated.
417 (This is a difference from most other debuggers where breaks occur
418 before the source line is executed.)
419
420 <P>In some cases the break occurs in a slightly different place from
421 where you would expect it.
422 This is the reason the <tt>break</tt> command optionally covers more
423 than one source line.
424 By setting breakpoints on a few lines around the interesting spot you
425 may make sure that there really is a break.
426
427 <P>A source line cannot have more than one breakpoint.
428 Each <tt>break</tt> command silently supersedes any previous breakpoints
429 it happens to overlap.
430
431 The <tt>clear breakpoint</tt> removes a breakpoint.
432
433 <H5><A NAME="identifying-brk">Identifying Breakpoints</A></H5>
434
435 <P>A breakpoint is identified by a small integer, the <em>breakpoint
436 number</em>.
437 The <tt>break</tt> command prints the breakpoint number of the
438 breakpoint it creates.
439 The breakpoint number can be used in other debugging commands.
440
441 <P>You may identify a breakpoint by its literal breakpoint number, or by
442 the special symbols '<tt>.</tt>' (dot) and '<tt>$</tt>' (dollar).
443 Dot means the <em>current</em> breakpoint, i.e. the breakpoint that
444 caused the current break.
445 Dollar means the <em>last</em> breakpoint defined by a <tt>break</tt>
446 command.
447
448 <P>Use the <tt>info breakpoint</tt> command to see the definition of a
449 breakpoint (or all breakpoints).
450
451 <H5><A NAME="tailoring-brk">Tailoring a Breakpoint</A></H5>
452
453 <P>A plain breakpoint as created by <tt>break</tt> is unconditional.
454 There are several ways you may modify its behavior to suit your needs.
455
456 <UL>
457 <LI>The <tt>ignore</tt> command sets an <em>ignore counter</em> on a
458 breakpoint.
459 A breakpoint having a non-zero ignore counter does not cause a break
460 when execution runs into it.
461 Instead of causing a break the ignore counter is decremented by one.
462 Setting an ignore counter to a negative value effectively disables
463 the breakpoint.
464
465 <LI>The <tt>condition</tt> command defines a condition for a
466 breakpoint.
467 The condition will be evaluated each time execution reaches the
468 breakpoint.
469 If the condition fails the breakpoint does not cause a break.
470
471 <LI>The <tt>do</tt> command attaches an anonymous macro (one or more
472 debugging commands) to a breakpoint.
473 The macro is executed whenever the breakpoint causes a break.
474 </UL>
475
476 <P>When a plain break occurs a special macro called the <em>prelude</em> is
477 executed.
478 The standard prelude prints the breakpoint number and the location of
479 the breakpoint.
480 In a similar way a special macro called the <em>postlude</em> is
481 executed just before execution is resumed after a break.
482 The standard postlude is empty.
483
484 <P>The prelude and postlude are ordinary macros which you may redefine by
485 means of the <tt>set</tt> command.
486
487 <P>Note that the prelude is not executed if a break is caused by a
488 breakpoint with a <tt>do</tt> macro.
489
490 <H5><A NAME="brk-0">Breakpoint 0 (Zero)</A></H5>
491
492 <P>Breakpoint zero is special.
493 The <tt>next</tt> debugging command causes a break to occur after the
494 next source line has been executed (or after a specified number of
495 lines).
496 A break caused by a <tt>next</tt> command is treated as if defined by
497 breakpoint number zero.
498 (This is the case even if there is an ordinary breakpoint on the same
499 source line.)
500 Breakpoint number zero may be assigned a condition, a <tt>do</tt> macro,
501 or an ignore count, just like other breakpoints.
502 It may not be cleared, however.
503
504 <H4><A NAME="expressions">Expressions</A></H4>
505
506 <P>Expressions may be included in the various print commands and in
507 breakpoint conditions.
508 Expressions may be formed from
509 <UL>
510 <LI>a large subset of Icon operators, including subscripting and
511 record field references,
512 <LI>integer, string, list literals,
513 <LI>locals from the current procedure,
514 <LI>globals,
515 <LI>procedure and function invocations,
516 <LI>a subset of the Icon keywords.
517 </UL>
518
519 <P>A few keywords have been added or altered:
520 <DL>
521 <DT>&amp;bp, &amp;breakpoint<DD>The breakpoint number of the current
522 breakpoint (integer).
523
524 <DT>&amp;file<DD>The source file name of the current breakpoint (string).
525
526 <DT>&amp;line<DD>The source line number of the current breakpoint (integer).
527
528 <DT>&amp;proc<DD>The name of the procedure where the current breakpoint
529 occurred (string).
530 </DL>
531
532 <P>Expression evaluation is guarded by error conversion.
533 An Icon error during evaluation should cause a conflict message, but
534 not terminate the program.
535
536 <H4><A NAME="printing-cmd">Commands for Printing</A></H4>
537
538 <P>There are several debugging commands for evaluating and printing
539 expressions.
540
541 <P>The <tt>print</tt> command takes any number of expressions separated by
542 semicolon.
543 The command evaluates and prints the image of the first value returned
544 by each expression.
545 This is a common way to inspect variables, for instance.
546
547 <P>The <tt>eprint</tt> command (<em>e</em> as in <B>every</B>) takes a single
548 expression and prints the image of every value it generates.
549 The following example shows a simple way of printing the contents of a
550 list,
551 <P><CODE>
552 eprint !mylist
553 </CODE>
554 <P>The <tt>fprint</tt> command (<em>f</em> as in <em>format</em>)
555 expects a format string followed by any number of expressions.
556 The format string can be any expression returning a string-convertible
557 value.
558 The expressions must be separated by semicolon.
559 The format string may contain placeholders.
560 The remaining expressions are expected to return values to insert into
561 the format string, replacing the placeholders.
562 In this case the actual value is used, not the image.
563 A conflict is generated if any of the values is not
564 string-convertible, so you may have to use the <B>image</B> function,
565 or some other explicit conversion.
566
567 <P>The <tt>fprint</tt> command is useful when you care about the appearance
568 of the output.
569
570 <P>The <tt>fprint</tt> command does not print a newline unless it is
571 explicitly included in the output.
572 Usually it can be inserted at the end of the format string.
573
574 <P>A format string placeholder is basically a percent (<tt>%</tt>) character
575 followed by a digit 1-9.
576 Thus there can be up to nine different placeholders.
577 A particular placeholder ('<tt>%1</tt>' for example) may occur any
578 number of times.
579 Each occurrence of '<tt>%1</tt>' will be replaced by the value of the
580 first expression after the format string.
581 Each occurrence of '<tt>%2</tt>' will be replaced by the value of the
582 second expression after the format string, and so on.
583
584 <P>A plain placeholder represents a variable-length field.
585 It is possible to specify a fixed-length field.
586 Add '<tt>&lt;</tt>' for a left-justified, or '<tt>></tt>' for a
587 right-justified field.
588 Also add the length of the field.
589 For instance, '<tt>%1&lt;20</tt>' defines a left-justified field with a fixed
590 length of 20 characters.
591
592 <P>To print a percent character, double the character in the format
593 string (<tt>%%</tt>).
594 Backslash (<tt>\</tt>) can also be used to quote other characters.
595
596 <P>A placeholder for which there is no value is silently replaced by its
597 placeholder number.
598
599 <H3><A NAME="run-quirks-limit">Run-Time Quirks, Limitations</A></H3>
600
601 <P>The <EM>itweak</EM> algorithm for deciding source line limits is
602 rather simple-minded.
603 This is the reason breaks do not always occur exactly where you
604 expect.
605
606 <P>The implementation of the alternation (<tt>|</tt>) control structure is
607 naive; works only in simple cases.
608 (See <cite>The Icon Analyst,</cite> Number 23, April 1994.)
609
610 <P>It is currently not possible to list macro definitions (including
611 <tt>do</tt> macros).
612
613 <P>A few commands use the <em>display file</em>: <tt>frame, info globals,
614 where</tt>.
615 The display file is simply the output from the <B>display</B> Icon
616 function.
617 Writing the display file requires write permission in the current
618 directory.
619
620 <P>It should be possible to negate a breakpoint condition, but this is
621 not implemented yet.
622
623 <P>It is possible to invoke a target program procedure in an expression.
624 This can be useful for side effects.
625 The run-time is not fully re-entrant, however, so if there is a
626 breakpoint in the procedure the run-time may get confused when it
627 returns.
628 (No fatal error should occur.)
629
630 <P>Escaping characters in <tt>fprint</tt> format strings do not always work.
631 Beware of the following format string.
632 It generates a long, long output.
633 <CODE>"foo/year=%1<20\1994\n"</CODE>
634
635 <H2><A NAME="performance">7. Performance Considerations</A></H2>
636
637 <P>My main dissatisfaction with the <em>debugify</em> package was
638 performance.
639 Thus a lot of effort has gone into finding ways to minimize the
640 debugging overhead.
641 The following performance measurements were made on a Sun SPARCstation
642 IPC under SunOS 4.1.3 with 24 Mb of memory.
643
644 <P>A tweaked ucode file will be less than 2 times the size of the
645 untweaked file (<em>debugify:</em> 5 times).
646 A tweaked program without any breakpoints (<tt>goon nobreak</tt>) runs
647 approximately 4 times slower than an untweaked program
648 (<em>debugify:</em> 200 times; this easily becomes unbearable).
649 The <EM>itweak</EM> program itself runs at over 3 times the speed of
650 <em>debugify</em>.
651
652 <P>The increased performance carries a certain cost: Only a single
653 potential breakpoint is created per source line.
654 No provision is made for setting variables.
655 The code is not executable unless certain global variables (created by
656 <EM>itweak</EM>) have been initialized.
657
658 <P>Debugging commands are compiled to an internal representation as they
659 are entered.
660 This is especially important for expressions.
661 Expressions are parsed with simple string matching, backtracking and
662 all.
663 They are immediately unwound and converted to a postfix notation.
664 This means that breakpoint conditions and macros can be evaluated
665 efficiently.
666
667 <H2><A NAME="impl-notes">8. Implementation Notes (The Hidden Art of Tweaking)</A></H2>
668
669 <P>The Icon source code generated by <EM>itweak</EM> mainly creates and initializes
670 a number of global variables.
671 An Icon <B>set</B> is created for each tweaked source file.
672 The sets are used to hold breakpoint line numbers.
673
674 <P><EM>itweak</EM> creates a potential breakpoint on every source line
675 it finds in the ucode file.
676 A potential breakpoint consists of code testing the current line
677 number against the set of breakpoint line numbers for the
678 current source file.
679
680 <P>If the test says 'yes' then a jump is made to code added at the end of
681 the current procedure.
682 This code collects the values and names of all locals and calls the
683 debugging run-time.
684 The same code is used for all potential breakpoints in one procedure.
685 This means that besides potential breakpoints a chunk of code is added
686 at the end of every procedure.
687
688 <P>A global variable named <tt>__dbg_test</tt> is used to test for
689 breakpoints.
690 It may be set to different Icon functions to achieve various effects.
691 The function will be called with two parameters: a set of breakpoint
692 line numbers and an integer line number.
693 The following values are currently used,
694
695 <DL>
696 <DT>member<DD>This is the initial value.
697 The effect is to check if there is a breakpoint on the current line.
698
699 <DT>integer<DD>Always fails (since a set cannot be converted to an
700 integer).
701 Used to implement the <tt>goon nobreak</tt> command.
702
703 <DT>2<DD>(integer 2)
704 The effect is to cause the second parameter to be returned.
705 Hence always succeeds.
706 Used to implement the <tt>next</tt> command which causes a break on
707 every potential breakpoint.
708 </DL>
709
710 <P>The debugging run-time is a procedure.
711 It must fail in order not to disturb the logic of the current
712 procedure.
713
714 <P>It surprises me that it is possible to do this amount of tweaking to
715 an Icon program.
716 I have debugged fairly complex programs without noticing any
717 unexpected weirdness (like tweaked program logic).
718 However, <EM>itweak</EM> as a whole is a case of reverse engineering.
719 Someone with greater theoretical insight may be able to detect cracks
720 in the tweaking scheme.
721 Please tell me in such case.
722
723 </BODY>
724 </HTML>