
Introduction
------------

Bug hunting in LessTif isn't really all that different from bug hunting in
X application code, with a few notable exceptions.  We encourage users to
help us make LessTif a better product by doing some preliminary ground-work
for the developers when you find a bug in the library.  Of course, what
we really want is a patch that fixes the bug, but we'll settle for some
help (grin).


What you'll need
----------------

A right-handed smoke bender, a Snark, a few slithy toves,... Oh.  Wrong
project (that's for work).  Ummm.  Let's see:

 o - a computer (Ta-dah!)
 o - the X Window System
 o - a compiler/assembler/linker
 o - a debugger
 o - some test code

Of course, if you don't have that, you probably don't need to read this,
do you?


What you'll want
----------------

The following list of books are nice to have, especially the Intrinsics
and the Motif books, but you can probably get away without them if you
have a full set of man pages.  One thing, though: if you want to understand
what widget methods do, and how a widget works, they are an absolute necessity.

The O'Reilly books "The Definitive Guide to the X Window System".  Of these,
you'll want:
	Volume 1: Xlib Programming Manual
	Volume 2: Xlib Reference Manual
	Volume 4: X Toolkit Intrinsics Programming Manual
	Volume 5: X Toolkit Intrinsics Reference Manual
	Volume 6A: Motif Programming Manual
	Volumn 6B: Motif Reference Manual
  If you have R6 (Linux, *BSD, others), you'll want:
	Programmer's Supplement for Release 6

From the OSF, you'll want
	OSF/Motif Programmer's Reference
  The style guide is nice, but not required.


What we need
------------

Why, patches, of course.  Failing that, we need sample code, and a stack trace
of the problem (even if it was an X Error -- more on this later).  If it was
a behavioral or visual problem, just a description will do, although some
code that exhibits the behavior would be nice.  We also need the version
number of the file that had the problem.  You can find this in the file
header (look for the $Id line in the file, or the rcsid).


Where to begin
--------------

Ok, your favorite Motif program is barfing on lesstif, and you're so inclined
to help us fix the problem.  Problems generally fall into four categories:
  o - behavior
  o - visual
  o - X Error
  o - core dump
Of these, the first two are more trivial, and (as of now, anyway) are allocated
somewhat lower priority, while we work on implementing *missing* behaviors.
X Errors and core dumps have a higher priority.

One thing to keep in mind is that the location that the problem occurs in
not necessarily the same as the location that caused the problem; this is
due to the (normally) asynchronous nature of X applications.  When your
application has a problem, the first thing to do is run the application
synchronously, to see if the location of the error changes (you'll be surprised
how often it will).  Here's how to do it with gdb:

root@zeek:/var/root/lesstif/testXm/filesb# gdb ./test1
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.14 (i586-unknown-linux), Copyright 1995 Free Software Foundation, Inc...
(no debugging symbols found)...
(gdb) run -sync
Starting program: /var/root/lesstif/testXm/filesb/./test1 -sync

-----
It'll probably spit out a bunch of debug messages (especially if you set
the DEBUGSOURCES environment variable).  Note that the commands passed to
the run command are actually command line arguments to the program.

On some systems, you may find that you can't set breakpoints at the start
if you use shared libraries.  That's because the symbols won't be resolved
until a process image exists.  To work around this, set a breakpoint at
main(), and run.  Once the breakpoint at main is reached, you'll find that
you can set the other breakpoints.

Once you've had your program dump core:), just say "where".  Again from gdb:
----------

Program received signal SIGSEGV, Segmentation fault.
0x40076918 in __XmStringGetNextComponent (context=0x8081de0) at XmString.c:68
68          if (context->current_segment < context->string->number_of_segments)
(gdb) where
#0  0x40076918 in __XmStringGetNextComponent (context=0x8081de0)
    at XmString.c:68
#1  0x40077ea7 in XmStringGetLtoR (string=0x30, 
    tag=0x804dc68 "FONTLIST_DEFAULT_TAG_STRING", text=0xbffffa00)
    at XmString.c:869
#2  0x8049793 in cb (w=0x8062c00, a=0x0, b=0xbffffa64) at test1.c:32
#3  0x400aa718 in XtCallCallbackList ()
#4  0x4005e7f0 in _XmSbButton (w=0x806cb00, client=0x0, call=0xbffffac0)
    at SelectionBox.c:467
#5  0x400aa743 in XtCallCallbackList ()
#6  0x4004e5a0 in Activate (w=0x806cb00, event=0xbffffce4, params=0x0, 
    num_params=0x0) at PushBG.c:1014
#7  0x4004f10b in input_dispatch (gadget=0x806cb00, event=0xbffffce4, 
    event_mask=64) at PushBG.c:1360
#8  0x40035ad6 in _XmDispatchGadgetInput (w=0x806cb00, event=0xbffffce4, 
    mask=64) at GadgetUtil.c:205
#9  0x40045492 in _XmGadgetActivate (w=0x8062c00, event=0xbffffce4, 
    params=0x0, num_params=0x8059668) at Manager.c:795
#10 0x400d2ceb in HandleActions ()
#11 0x400d35ae in HandleComplexState ()
#12 0x400d365b in _XtTranslateEvent ()
#13 0x400b412f in XtDispatchEventToWidget ()
#14 0x400b4aa9 in _XtDefaultDispatcher ()
---Type <return> to continue, or q <return> to quit---
#15 0x400b4ce3 in XtDispatchEvent ()
#16 0x400b4fd9 in XtAppMainLoop ()
#17 0x80498f1 in main (argc=1, argv=0xbffffd78) at test1.c:69
#18 0x80495a4 in ___crt_dummy__ ()

Note the line numbers.  Please do NOT send a trace without having compiled with
debug (the -g option).

About X Errors
--------------

Sometimes the program will fail with something like:

X Error: Bad Drawable
  (other stuff)
or something similar.  This is a problem with something that got sent to the
X server.

This isn't hard to track down if you've run in synchronous mode.  Just set
a breakpoint at the exit() function, run with the -sync option, and you'll
get a trace from the point where the error occurred, plus some other
information.  These are crucial to proper LessTif functionality -- these
must be stamped out.
[this needs more detail]

About using send-pr
-------------------

Now that we've gotten GNATS set up, there is a quick way to send us problem
reports: the send-pr script.
[Chris, do you want to fill in stuff here?]

Conclusion
----------

HELP!! WE NEED HELP!!  Seriously folks, the more you help us, the better
LessTif gets.  We don't have access to your applications (well, not all of
them), so we rely on users to tell us what's broken.  Help us make LessTif
a viable alternative to Motif!

When you send a report, make sure you include the version number of the
source file at the root of the problem.  To get this, look in the source
file at the top:  for example,

 * $Id: BUG-HUNTING,v 1.1 1996/04/15 02:16:18 miers Exp $

This is critically important if you are working from a -current release, as
this tells us when you noticed the bug, and the file version you noticed
it in.  We may have fixed it already....
