/usr/share/doc/gri/html/KillingBugs.html is in gri-html-doc 2.12.23-9build2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Gri: bugs</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"></head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000EE" vlink="#551A8B" alink="FF0000">
<!-- newfile KillingBugs.html "Gri: bugs" "Gri Bugs" -->
<!-- @node Killing Bugs, Debugging Software You Will Need, Reporting Bugs, Bugs -->
<a name="KillingBugs" ></a>
<img src="./resources/top_banner.gif" alt="navigation map" usemap="#navigate_top" border="0">
<table summary="top banner" border="0" cellspacing="0" cellpadding="0">
<tr>
<td width="150" valign="top">
<font size=-1>
<br>
Chapters:
<br>
<a href="Introduction.html">1: Introduction</a><br>
<a href="SimpleExample.html">2: Simple example</a><br>
<a href="InvokingGri.html">3: Invocation</a><br>
<a href="GettingMoreControl.html">4: Finer Control</a><br>
<a href="X-Y.html">5: X-Y Plots</a><br>
<a href="ContourPlots.html">6: Contour Plots</a><br>
<a href="Images.html">7: Image Plots</a><br>
<a href="Examples.html">8: Examples</a><br>
<a href="Commands.html">9: Gri Commands</a><br>
<a href="Programming.html">10: Programming</a><br>
<a href="Environment.html">11: Environment</a><br>
<a href="Emacs.html">12: Emacs Mode</a><br>
<a href="History.html">13: History</a><br>
<a href="Installation.html">14: Installation</a><br>
<a href="Bugs.html">15: Gri Bugs</a><br>
<a href="TestSuite.html">16: Test Suite</a><br>
<a href="GriInThePress.html">17: Gri in Press</a><br>
<a href="Acknowledgments.html">18: Acknowledgments</a><br>
<a href="License.html">19: License</a><br>
<br>
Indices:<br>
<a href="ConceptIndex.html"><i>Concepts</i></a><br>
<a href="CommandIndex.html"><i>Commands</i></a><br>
<a href="BuiltinIndex.html"><i>Variables</i></a><br>
</font>
<td width="500" valign="top">
<map name="navigate_top">
<area alt="index.html#Top" shape="rect" coords="5,2,218,24" href="index.html#Top">
<area alt="Bugs.html#Bugs" shape="rect" coords="516,2,532,24" href="Bugs.html#Bugs">
<area alt="Gri: bugs" shape="rect" coords="557,2,573,24" href="ReportingBugs.html">
<area alt="Gri: Test Suite" shape="rect" coords="581,2,599,24" href="TestSuite.html">
</map>
<map name="navigate_bottom">
<area alt="index.html#Top" shape="rect" coords="5,2,218,24" href="index.html#Top">
<area alt="Gri: Test Suite" shape="rect" coords="581,2,599,24" href="TestSuite.html">
</map>
<h2>15.3: Killing Bugs</h2>
<UL>
<LI><a href="KillingBugs.html#DebuggingSoftwareYouWillNeed">Debugging Software You Will Need</a>:
<LI><a href="KillingBugs.html#DebuggingataGlance">Debugging at a Glance</a>:
<LI><a href="KillingBugs.html#DebuggingExample">Debugging Example</a>:
</UL>
<!-- @node Debugging Software You Will Need, Debugging at a Glance, Killing Bugs, Killing Bugs -->
<a name="DebuggingSoftwareYouWillNeed" ></a>
<h3>15.3.1: Software that you'll need</h3>
This section is intended to help you find and kill bugs yourself, by
indicating how the author does this work. Since Gri is open-source,
all users are invited to try to kill bugs themselves!
<p>
If you know nothing of C or C++, you may as well not read further,
since there is little chance of your making progress. On the other
hand, experienced programmers won't need any of the advice I give
below.
<p>
You'll need the Gri source and a C++ compiler. It also helps if you
have `<font color="#82140F"><code>gdb</code></font>', the GNU debugger, installed; the instructions below
assume that's the case. Also, the instructions assume that you're
using the Emacs editor, and running `<font color="#82140F"><code>gdb</code></font>' from within Emacs.
Otherwise, you'll want to glance at the documentation on `<font color="#82140F"><code>gdb</code></font>' to
see how to use it in standalone mode.
<p>
<!-- @node Debugging at a Glance, Debugging Example, Debugging Software You Will Need, Killing Bugs -->
<a name="DebuggingataGlance" ></a>
<h3>15.3.2: Debugging at a glance</h3>
The list below is a sketch of what you might try, and in what order.
<p>
<ul>
<p>
<li> Check the bug list to see if other users have found your bug,
and also to see if there is a workaround.
<p>
<li> Try a more recent version of gri. If it works, you might wish to
archive the version you have at the moment and upgrade.
<p>
<li> If you suspect your bug has something to do with system calls,
as in the `<font color="82140F"><code>system</code></font>' command (see <a href="System.html#System">System</a>) or as in piped input
files (see <a href="Open.html#Open">Open</a>), you should re-run the script with
`<font color="#82140F"><code>gri -superuser8</code></font>' instead of with `<font color="#82140F"><code>gri</code></font>'. This will cause
Gri to print out all commands that it is handing over to the operating
system; you may see the error that way. (Hint: it may help to
interactively cut/paste the commands into your OS shell to see what the
action of the command is.)
<p>
<li> If your bug results in early termination, you should run Gri
inside a debugger (e.g. GDB, assumed henceforth). When the program
terminates, type `<font color="#82140F"><code>where</code></font>' to see where termination occured. Often
this will give a clue. In many cases, early termination results from
faults in memory allocation. To check memory allocation, you'll need to
recompile Gri, linking it against a debugging memory allocator. Many
such tools exist; see comments in the `<font color="#82140F"><code>Makefile</code></font>' for a hint at how
to use a popular one, called ``Electric Fence.''
<p>
<li> If your bug does not result in early termination, you may find
the best scheme is to trim your example down as much as possible, and
then run Gri inside the GDB (or other debugger) so that you can monitor
program execution. The next section explains this in detail.
</ul>
<p>
<!-- @node Debugging Example, Test Suite, Debugging at a Glance, Killing Bugs -->
<a name="DebuggingExample" ></a>
<h3>15.3.3: A debugging Example</h3>
Let's take a recent bug as an example. Peter Galbraith found that the
gri script
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
set color hsb 0.999 1 1
draw box filled 2 2 3 3 cm
set color hsb 1.000 1 1
draw box filled 4 2 5 3 cm
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
produced odd results in a previous version of Gri; the color patches
should have been of nearly the same color, but the first one was red, as
expected, and the second was magenta.
<p>
The list below shows how I found Peter's bug. Experienced C or C++
programmers will find all of this very familiar, and will really only
need to read item 6 of the list below, since that's the only action that
is really specific to Gri. (Note: for display purposes, I've broken
some of the lines in the files into two lines in this list.)
<p>
<ol>
<p>
<li> Copy the above script (called `<font color="#82140F"><samp>test.gri</samp></font>') into the Gri source
directory, and the script into an Emacs buffer. <b>Note:</b> all the
following steps are done within Emacs, and the items in parentheses are
the Emacs keys to get the indicated actions.
<p>
<li> If you're working from a pre-compiled version, you'll need to get the
source first and do a compile yourself (see <a href="uncompiled-unix.html#UncompiledUnix">Uncompiled Unix</a>). Then do
a `<font color="#82140F"><code>make tags</code></font>' command (type this to the unix shell) to create a
so-called "tag" table.
<p>
<li> Run Gri in this emacs buffer (`<font color="#82140F"><kbd>C-cC-r</kbd></font>') noting from the
postscript window that pops up that the colors are, indeed, mixed up.
<p>
<li> Load up the `<font color="#82140F"><code>gdb</code></font>' debugger by typing `<font color="#82140F"><kbd>M-x gdb gri</kbd></font>'. This
will open a new Emacs buffer in which you may type commands. We'll be
switching back and forth between this buffer and various source files.
<p>
<li> Reasoning that the error probably occurs at `<font color="#82140F"><code>set color</code></font>' or
`<font color="#82140F"><code>draw box</code></font>', try replacing the latter by a command such as
`<font color="#82140F"><code>draw label "hi" at 3 3 cm"</code></font>'. The color is still wrong, indicating
that it is the `<font color="#82140F"><code>set color</code></font>' command that has the problem.
<p>
<li> Next, we must find where the C++ code corresponding to the
`<font color="#82140F"><code>set color</code></font>' command resides. As it turns out, all `<font color="#82140F"><code>set</code></font>'
commands are defined in the source file `<font color="#82140F"><code>set.cc</code></font>', and this command
is defined in a subroutine called `<font color="#82140F"><code>set_colorCmd()</code></font>'. But the author
knows this -- how would you? The answer is to look in the
`<font color="#82140F"><samp>gri.cmd</samp></font>' file, for the `<font color="#82140F"><code>set color</code></font>' command. (Search for the
string `<font color="#82140F"><code>`set color </code></font>'.) Then read down to see the body of the
command, enclosed in braces; you'll see
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
{
extern "C" bool set_colorCmd(void);
}
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
which indicates that the subroutine name is `<font color="#82140F"><code>set_colorCmd()</code></font>'.
<p>
<li> Next we need to edit this subroutine to see what it is doing.
There are several ways to find it (e.g. `<font color="#82140F"><code>grep</code></font>' through the source
files), but the easiest is to use the "tags" feature of Emacs, by typing
`<font color="#82140F"><kbd>M-. set_colorCmd</kbd></font>'. This will bring you to the indicated
subroutine.
<p>
<li> Have a look through this subroutine to see what it is doing. It
looks very much like many other Gri subroutines. A check is done on the
number of words provided to the command, in the
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
switch (_nword) {
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
line. (That's line `<font color="#82140F"><samp>set.cc:484</samp></font>' at the moment -- but it may be
different by the time you read this file, if I've changed it!) We are
calling it with 6 words (`<font color="#82140F"><code>set color hsb 1.000 1 1</code></font>'), so move down
to the line
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
case 6:
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
and you'll see that there is an `<font color="#82140F"><code>if</code></font>' statement seeing whether this
word is `<font color="#82140F"><code>rgb</code></font>' or `<font color="#82140F"><code>hsv</code></font>'. These statements are checking
`<font color="#82140F"><code>_word[2]</code></font>', which is the third word of the command. (In Gri, as in
C, words start at zero. Thus, for this command, `<font color="#82140F"><code>_word[0]</code></font>' is
`<font color="#82140F"><code>set</code></font>', `<font color="#82140F"><code>_word[1]</code></font>' is `<font color="#82140F"><code>color</code></font>', and `<font color="#82140F"><code>_word[2]</code></font>' is
expected to be either `<font color="#82140F"><code>rgb</code></font>' or `<font color="#82140F"><code>hsb</code></font>'. We are having problems
with the `<font color="#82140F"><code>hsb</code></font>' style, so we'll move down to that code. The code
that's being executed is as follows.
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
} else if (!strcmp(_word[2], "hsb")) {
// `set color hsb .hue. .saturation. .brightness.'
double hue, saturation, brightness;
Require(getdnum(_word[3], &hue),
READ_WORD_ERROR(".hue."));
Require(getdnum(_word[4], &saturation),
READ_WORD_ERROR(".saturation."));
Require(getdnum(_word[5], &brightness),
READ_WORD_ERROR(".brightness."));
// Clip if necessary
CHECK_HSB_RANGE(hue);
CHECK_HSB_RANGE(saturation);
CHECK_HSB_RANGE(brightness);
gr_hsv2rgb(hue, saturation, brightness,
&red, &green, &blue);
PUT_VAR("..red..", red);
PUT_VAR("..green..", green);
PUT_VAR("..blue..", blue);
c.setHSV(hue, saturation, brightness);
_griState.set_color_line(c);
if (_griState.separate_text_color() == false)
_griState.set_color_text(c);
return true;
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
The `<font color="#82140F"><code>Require</code></font>' lines are ensuring that we could decode the values of
the variables `<font color="#82140F"><code>hue</code></font>', etc, from the commandline. Then we clip the
range of these values. Then we convert from `<font color="#82140F"><code>hsb</code></font>' color format to
`<font color="#82140F"><code>rgb</code></font>' color format, save the values of the colors in Gri variables
with `<font color="#82140F"><code>PUT_VAR</code></font>', and then set the color with `<font color="#82140F"><code>c.setHSV</code></font>'.
Finally we save this color in the Gri "state" with
`<font color="#82140F"><code>_griState.set_color_line(c)</code></font>'.
<p>
As it turns out, Gri outputs all colors to the PostScript file in RGB
format, so the we may well suspect that the problem is in the
`<font color="#82140F"><code>gr_hsv2rgb()</code></font>' line.
<p>
<li> We have an idea where to look now, so let's go to the line just after
it, in the editor, and insert a "breakpoint" there by typing
`<font color="#82140F"><kbd>C-x SPC</kbd></font>'. Then move to the `<font color="#82140F"><code>gdb</code></font>' buffer and re-run Gri
by typing
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
run -directory . test.gri
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
to run Gri on our script. Then, magic happens! Gri stops at the
indicated breakpoint, and Emacs will display both the `<font color="#82140F"><code>gdb</code></font>' buffer
and the `<font color="#82140F"><code>set.cc</code></font>' buffer. The latter has a margin indication
telling what line were are on. You may now type `<font color="#82140F"><code>gdb</code></font>' commands in
the `<font color="#82140F"><code>gdb</code></font>' buffer. In particular, type
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
p hue
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
to print the hue. Then type
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
p red
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
to see the red value. Then type
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
c
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
to continue running Gri. It will pause again. Check the hue and red
values again, as above. If you like, play around with hue value in the
Gri script `<font color="#82140F"><samp>test.gri</samp></font>' and run gri again (type `<font color="#82140F"><code>r</code></font>' in
`<font color="#82140F"><code>gdb</code></font>'). This seems to indicate that the conversion is working
strangely.
<p>
<li> To see how the conversion is done, clear the breakpoints by typing
`<font color="#82140F"><kbd>delete</kbd></font>' in the `<font color="#82140F"><code>gdb</code></font>' buffer, then insert a breakpoint
<b>before</b> `<font color="#82140F"><code>gr_hsv2rgb</code></font>' is called. Then, run Gri again (`<font color="#82140F"><kbd>r</kbd></font>'
in the `<font color="#82140F"><code>gdb</code></font>' buffer). When it stops just before this subroutine,
type `<font color="#82140F"><kbd>s</kbd></font>' to "step into" the subroutine. Then you'll see a
conversion code from the (wonderful) textbook of Foley and Van Dam.
You'll see
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
void
gr_hsv2rgb(double h, double s, double v,
double *r, double *g, double *b)
{
h = 6.0 * pin0_1(h);
s = pin0_1(s);
v = pin0_1(v);
int i = (int) floor(h);
if (i > 5)
i = 5; // Prevent problem if hue is exactly 1
double f = h - i;
double p = v * (1.0 - s);
...
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
in the present version of Gri, but in the previous (buggy) version, the
`<font color="#82140F"><code>if</code></font>' statement was missing. Without this `<font color="#82140F"><code>if</code></font>' statement, Gri
produced wrong colors. With the statement, the colors are correct.
</ol>
And so ends the example. You may wish to read the Foley and Van Dam
textbook to see just what I'm doing in `<font color="#82140F"><code>gr_hsv2rgb</code></font>', but suffice it
to say that the problem in the (older) version of Gri was that `<font color="#82140F"><code>i</code></font>'
could take the value 6 if the hue was exactly equal to 1, and that was
erroneous.
<p>
In reading the code, you may notice that it is formatted in a uniform
way: the Kernighan and Ritchie scheme (from their classic C textbook),
with 8-character indents. I get this by putting the following lines
in the `<font color="#82140F"><samp>~/.emacs</samp></font>' file, which is used to customize the Emacs editor:
<p>
<TABLE SUMMARY="Example" BORDER="0" BGCOLOR="#efefef" WIDTH="100%">
<TR>
<TD>
<PRE>
<font color="#82140F">
(defun my-c-mode-common-hook ()
(c-set-style "K&R")
(setq c-basic-offset 8)
)
(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
</font></PRE>
</TD>
</TR>
</TABLE>
<p>
If you submit patches, please use the same format as I've done, so
that I can more easily see the changes you've made.
<p>
</table>
<img src="./resources/bottom_banner.gif" alt="navigation map" usemap="#navigate_bottom" border="0">
</body>
</html>
|