                    Reporting Bugs and Submitting Fixes

Table of Contents

     * [1]Introduction
     * [2]What you'll need to find bugs
     * [3]Recommended reading
     * [4]Isolating bugs
     * [5]X Protocol Errors
     * [6]Submitting bug reports
     * [7]Submitting patches
     * [8]Where to send bug reports and fixes

Introduction

   Bug  hunting  in  LessTif  isn't  really  all  that different from bug
   hunting   in   arbitrary  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.

What you'll need

   Let's see:
     * a computer (Ta-dah!)
     * the X Window System, at release level R5 or above
     * a compiler/assembler/linker
     * a debugger
     * some test code

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

Recommended Reading

   First  of  all you should check our own tutorial on [9]Bug Hunting! It
   explains  in  detail  the  built-in  debugging  facilities  within the
   LessTif libraries.

   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
     * Volume 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 (for 1.2)
     * OSF/Motif Programmer's Guide (for 1.2)

   The style guide is nice, but not required.

   Further details on debugging X11 apps can be found at these writings:
     * [10]www.openmotif.org/tnt/#Debug_Breakpoints
     * [11]www.rahul.net/kenton/perrors.html

Isolating bugs

   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
   broad categories:
     * Behavior
     * Visual
     * X Protocol Error
     * 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  DEBUG_SOURCES  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". This also
   works  if your program just crashed when not running within a debugger
   but it created a core dump. Then just start
   gdb program core
   and type "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 Protocol Errors

   Sometimes the program will fail with:
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.

Submitting bug reports

   When (not if) you find a problem with LessTif, we really want to know.
   In  first  place we need a detailed description of the problem and you
   specific system. Try to be as complete as you can - if you send just a
   description like
   Well,  I  ran  an  app,  and the thingie at the bottom of the wossname
   didn't look right
   you are in all likelihood going to be ignored.

   On  the  application  side  specify which program version (including a
   reference  where  to  get  it if it's a "free" application) and how to
   reproduce  the bug. Sometimes one will ran into non-reproducible ones.
   You  should also report them, but due to their somewhat obscure nature
   they're  hard to track down perhaps. Further we need details about the
   version of LessTif you have installed. These include:
     * version number
     * distribution (a binary package, or did you build from sources)
     * if  being  built  from sources the configuration options may be of
       interest

   Finally we need to know about your system: which hardware platform (no
   details  about  specific  hardware, but name the CPU architecture) and
   which operating system. On un*x uname -a gives helpful information.

   Ideally,  a patch is what we would prefer to receive. Failing that, we
   need  sample code, and a stack trace of the problem (even if it was an
   X Error). 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. If
   you  prefer,  and  you  are using lesstif-current, you can tell us the
   date  you  noticed  the problem. Please do not tell us the problem two
   months  after  you saw it, the code base changes too rapidly for us to
   be able to make anything meaningful out of a bug report that old.

Submitting patches

   Patches  are  the  preferred  form  of  bug  report, as it lessens our
   efforts  to  track  down where the bugs are. If you do submit a patch,
   please try to keep a few rules in mind.
   First the most important ones:
     * Explain what the changes should do and why they improve things!
     * Always  create  patches against the latest official source release
       or even our code as in our public [12]CVS repository!
     * Specify  exactly  against  which  version of the code the diff was
       created!
     * We  can only accept patches in the "unified diff" format (with GNU
       diff,  this is "diff -u"). If you want to, you can send a "context
       diff" ("diff -c").
     * Always  ensure that the code still builds and links completly (use
       dependency  tracking  or  "make  clean"  to  be  sure).  Also  the
       resulting  binary  should still work, and even better then before,
       so please run more than one test only!
       A good idea is to run our examples within our [13]test/ tree.

   Some more things to consider:
     * When  writing  your  fix, please try to follow the coding style of
       the  file  you  are  fixing.  We  are  currently  debating  coding
       standards, so expect to see one soon.
     * Try  not  to submit a fix that creates dead code. Using "#if 0" or
       commented code is discouraged. We can do that (because, after all,
       we are the elitist core team;), but you are discouraged from that,
       because it makes the patches hard to read.
     * Do  not  be  discouraged  if  your patch is not accepted verbatim.
       Often people submit patches that one or more of the core team will
       recognize  as  identifying  a  problem,  but  the core member will
       recognize   that   your   fix  will  break  some  other  piece  of
       functionality.  We'll  try to tell you, but we're human, so we may
       forget.
     * Remember  that relay mailers are free to alter the content of text
       messages,  and  often  do  so. Lines should always be less than 80
       characters in length.
     * If  you  are  working  on  a  non-un*x  platform  take care of the
       different   text  format  (e.g.  <carriage-return><line-feed>  vs.
       <line-feed> on DOS-related platforms)!

                    Where to send bug reports and fixes

   We have a working bugs database at SourceForge.net !
   You may add bugs by using
   [14]http://sourceforge.net/tracker/?atid=108596&group_id=8596.

   Patches can be sent to our [15]mailinglist if they are quite small. If
   they  are  big you should ask first where to send them. Patches of any
   size are also accepted (probably the best method) on our Patch Manager
   at
   [16]http://sourceforge.net/tracker/?atid=308596&group_id=8596&func=bro
   wse.

   Thanks, and remember:
   All help is appreciated!
     _________________________________________________________________


    [17]Valid HTML 3.2! [18]Feedback
    Last modified on $Date: 2003/10/24 11:21:12 $

References

   1. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/bugs.html#Introduction
   2. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/bugs.html#What
   3. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/bugs.html#Reading
   4. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/bugs.html#IsolatingBugs
   5. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/bugs.html#Protocol
   6. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/bugs.html#SubmittingBugs
   7. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/bugs.html#SubmittingPatches
   8. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/bugs.html#WhereToSend
   9. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/BUG-HUNTING.html
  10. http://www.openmotif.org/tnt/#Debug_Breakpoints
  11. http://www.rahul.net/kenton/perrors.html
  12. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/cvs.html
  13. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/BUG-HUNTING.html#testing
  14. http://sourceforge.net/tracker/?atid=108596&group_id=8596
  15. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/lists.html
  16. http://sourceforge.net/tracker/?atid=308596&group_id=8596&func=browse
  17. http://validator.w3.org/check/referer
  18. file://localhost/home/danny/tmp/ltrel/lesstif/doc/www.lesstif.org/feedback.html
