


 Reporting bugs and submitting fixes



    
      
    


Reporting bugs and submitting fixes


Table of Contents


Introduction
What you'll need to find bugs
Recommended reading
Isolating bugs
X Protocol Errors
Submitting bug reports
Submitting patches
Where to send bug reports and fixes


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.

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

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

The style guide is nice, but not required.

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 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-&gt;current_segment &lt; context-&gt;string-&gt;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 &lt;return&gt; to continue, or q &lt;return&gt; 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 detailled 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 &quot;free&quot; 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 configuraion 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:

 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. &lt;carriage-return&gt;&lt;line-feed&gt; vs.
      &lt;line-feed&gt; on DOS-related platforms)!

 We prefer patches in the "unified diff" format (with GNU diff, this is
      "diff -u").  If you have to, you can send a "context diff" ("diff -c").
      Please use one of those two formats.

 To make sure you are creating a patch based on the
     latest sources, you may retrieve the current development
     tree via anonymous
     CVS.



Where to send bug reports and fixes

Please send them by E-mail to
lesstif@hungry.com,
the LessTif mailing list.
(We've been using a bug tracking system at bugs.hungry.com
for a while but it broke and it seems to be beyond fixing.)


<!--
 Bug reports used to go to the
mailing list, but Chris Toshok set up <a
href="http://bugs.hungry.com">Bug Hungry, so we use that now.  If you
have any problems with Bug Hungry you can still send problem reports to
the mailing list.

-->
Thanks, and remember: all help is appreciated.





Please send comments, questions, ... to
the mailing list.







